Card 05/ 08
Transient vs Permanent Errors: Which a Client Should Retry
A 503 may succeed in a second; a 400 will fail the same way every time it is sent.
A transient error is one that may go away by itself, such as an overloaded server or a rate limit, so the same request may succeed later. A permanent error is caused by the request itself, so sending it again unchanged fails the same way every time. A client should retry only transient errors, and only when the request is safe to repeat.
When The response is 400, 401, 403, 404, 409 or 422
, chooseNo. Fix the request, refresh the credentials, or give up; the same request fails again.
When The response is 429, or a 503 with Retry-After
, chooseYes, after waiting at least the time the server gives.
When The response is 500, 502, 503 or 504, or the connection timed out, and the method is idempotent or the request carries an idempotency key
, chooseYes, a few times, waiting longer between each attempt.
When The same failure, but a POST or PATCH with no idempotency key
, chooseNot automatically; the first attempt may have succeeded, so check first.
429 is the transient 4xx. It is a client error, because the client sent too much, but the same request succeeds once the limit resets. A client that skips every 4xx never recovers from a rate limit.
Retry-After is the server's hint. It gives a wait in seconds, Retry-After: 30, or a date. A client should wait at least that long, and a server under load should send it on 429 and 503.
Waiting longer each time. Retrying at once, or at fixed intervals, can keep an overloaded server down as every client hits it together. Clients usually double the wait each attempt and add a random amount, and give up after a few tries. Retry policies in depth belong to resilient systems.
The rule for choosing. Retry when the error is transient and the request is safe to repeat; otherwise, fix the request or check what happened.
← → move through sections and cards