How it works
The client picks a key that identifies the operation, such as an order id or job id, and sends it with the request. The server stores the key with the result in the same transaction as the change. If the same key arrives again, the server returns the stored result instead of applying the change a second time.
A careful server also checks that a reused key belongs to the same request. A key sent again with a different amount or user is almost always a bug, so it should be rejected rather than silently answered with the earlier result.
Example
Your server deducts 25 credits for job 8812 with key job-8812, and the network times out. You do not know if it went through, so you retry with the same key. The first attempt had succeeded, so the retry returns the original result and the user is charged 25 credits, not 50.
Idempotency key in Cred
Send an Idempotency-Key header on /issue, /deduct, and /refund; a retry with the same key returns the original result with idempotent_replay: true. Keys are scoped to your project and never expire, reusing one for a different request returns 409 IDEMPOTENCY_KEY_REUSED, and POST /charge-saved requires one.
Managing Credits docsRelated terms
Questions
- What should I use as an idempotency key?
- An identifier of the business operation that already exists in your system, such as an order id, job id, or invoice id. Avoid random values generated per attempt, since a retry would then get a new key.
- Do GET requests need idempotency keys?
- No. Reads do not change state, so repeating them is already safe. Keys matter for requests that move money or balances.
