Amarseba API
Developer documentation
সেন্টারসমূহ
Idempotency and safe retries
Networks fail. When a request times out you cannot tell whether the server received it. An idempotency key lets you retry safely: the API performs the work once and replays the same response for every retry, so a retried send is never charged twice.
How to use it
- Send an
Idempotency-Keyheader onPOST,PATCHandDELETErequests. It is optional but strongly recommended on every send. - The key is any string of 1 to 255 characters; anything else returns
422 validation_errorunderidempotency_key. A UUID v4 per logical operation is ideal. - Generate the key once, before the first attempt, and reuse it for every retry of that same operation.
- Keys are scoped to the API key that sent them and remembered for 24 hours.
Idempotency-Key: 2f1c8e0a-6b4d-4c1e-9a53-7d0b1e4f8a21What happens on a retry
| Situation | Result |
|---|---|
| Same key, same method, path and body, first attempt succeeded | The stored response is returned with the header Idempotent-Replayed: true. No new work, no new charge. |
| Same key, different body or path | 409 idempotency_key_reused |
| Same key while the first attempt is still running | 409 request_in_progress: wait briefly and retry. |
| First attempt returned an error | Nothing was stored; the retry runs normally. |
A replay returns the stored first response, in the language of the first response, whatever Accept-Language the retry sends.
Only successes are stored
Only 2xx responses are remembered. Errors such as 402, 409, 422, 429 and 5xx are not, so you can fix the cause and retry with the same key. For example, after a 402 insufficient_balance you can top up your wallet and retry with the same Idempotency-Key: it is safe and charges exactly once.