Technical concepts
Retries
Retry a request when the failure is temporary, with the same Idempotency-Key and increasing waits. Do not retry a request that the API refused on purpose.
On this page
What to retry#
| Failure | Retry | Notes |
|---|---|---|
| Network error or timeout on your side | Yes | The request may have run. The same key makes the retry safe. |
429 |
Yes | Wait for Retry-After when present. See Rate limits. |
500 |
Yes | |
502, 503, 504 |
Yes | A 503 can have Retry-After. Wait at least that long. |
400, 413 |
No | Fix the request. |
401, 403 |
No | Fix the key or its scopes. |
404 |
No | Check the ID and the environment. |
409 |
No | Read the resource. For an idempotency conflict, the key was used for a different request. |
422 |
No | Read the message and change the data or the state. |
A 503 with the code providerPending means that the same request still runs. Retry later with the same key, or wait for the webhook event.
How to retry#
- Use the same
Idempotency-Keyfor every retry of an operation. See Idempotency. - Wait longer before each retry: for example 1, 2, 4, 8, and 16 seconds.
- Add random jitter to each wait.
- Stop after a fixed number of attempts or a fixed time, and alert a person.
- Keep all retries within 24 hours of the first request.
A GET request changes nothing, so you can retry it without a key.
Other kinds of retry#
Two other features have “retry” in their name. They are not request retries.
- Payment retry. Retry a payment starts a new attempt on a failed payment. It is a new action that can collect money. Call it only when the buyer or your policy wants a new attempt.
- Webhook retries. Merxian retries a webhook delivery when your endpoint does not answer
2xx. See Delivery and retries.