Idempotency

Every write endpoint (usage ingestion, contract mutations, and similar) requires an Idempotency-Key header. Relvo uses it to guarantee a request is processed at most once, even if you retry after a timeout or network error.

Idempotency-Key: 2f6a1e4c-9b3d-4a11-9e2f-6c1a8b0d5e77

How it works

• Send a unique key (a UUID is a good choice) with every write request.
• If Relvo has already completed a request with that exact key, it returns the original cached result instead of processing again — safe to retry as many times as needed.
• If the same key is reused with a different request payload, Relvo rejects it with a 409 and code: "idempotency.conflict" — this is a signal that your retry logic generated a new key incorrectly, or that two unrelated operations accidentally collided on the same key.

Practical guidance

• Generate the key once per logical operation, before the first attempt — not per HTTP call. A retry of the same operation must reuse the same key.
• Keys are scoped per endpoint; you do not need to coordinate uniqueness across different operations.
• There is no need to poll for “in progress” — if you retry while Relvo is still processing the original request, you’ll get a fast, safe rejection rather than a duplicate write.

Example

curl -X POST "https://app.relvoerp.com/api/v1/public/metering/usage-events" \
  -H "Authorization: Bearer rk_live_xxxxxxxxxxxxxxxxxxxx" \
  -H "Idempotency-Key: 2f6a1e4c-9b3d-4a11-9e2f-6c1a8b0d5e77" \
  -H "Content-Type: application/json" \
  -d '{ "...": "..." }'