Part 5 of 9 · 3 min read
Status codes, errors and idempotency keys
How a server reports results, and how to make a POST safe to retry.
Think of a post office receipt. It says "delivered", "address not found" or "sorting office on fire". The sender acts differently on each.
Status codes work the same way. The first digit sets the group.
| Range | Meaning | Retry? |
|---|---|---|
| 200–299 | Success | Not needed |
| 300–399 | Redirection | Follow the new address |
| 400–499 | The client made an error | Not unchanged: the same request fails again |
| 500–599 | The server had an error | Often yes, after a pause |
The book lists the usual ones. Success: 200 (OK). Redirect: 301 (moved permanently, with the new URL in a Location header). Client errors: 400 (bad input), 401 (not authenticated), 403 (authenticated but not allowed), 404 (not found). Server errors: 500 (generic failure), 502 (bad reply from a server behind), 503 (cannot serve right now, may later).
Read it as
4xx means "fix your request". 5xx means "my fault, try again later".
A good error reply also has a body that a program can read. A simple shape:
{
"error": "out_of_stock",
"message": "Only 3 units left",
"request_id": "a81f-77c2"
}
The error field is a short code that never changes. The message is for people. The request_id lets support find the exact request in the logs (Level 9).
Now the hard case. A POST that creates a payment is not idempotent. The client sends it, the connection drops, and no reply arrives. Retrying could charge the customer twice. The usual fix is a key.
Idempotency key
An idempotency key is a unique value the client sends with a request. The server remembers the key and the result. If the same key comes again, the server returns the saved result and does not repeat the work.
Example: the client sends Idempotency-Key: 7c1e with a charge of 20 dollars. A repeat with the same key returns the first answer, and the card is charged once.
The server side needs a small table.
| key | request body hash | status | saved reply |
|---|---|---|---|
| 7c1e | 5d2a | done | 200, charge 91 |
The steps on the server:
- Look up the key. If it is missing, start the work and save the key with the status "working".
- When the work ends, save the reply and set the status to "done".
- If the key arrives again and the status is "done", return the saved reply.
- If the key arrives while the status is "working", return a "try again" error, so that two copies never run together.
- If the key arrives with a different body, return an error. A key must belong to one request only.
A worked example. A customer pays 20 dollars. The first call reaches the server, the card is charged, and the reply is lost. The client waits, and sends the same call with the same key. The server finds the key marked "done" and returns "charge 91" again. The customer pays 20 dollars, not 40.
The key should come from the client and be chosen before the first attempt, for example a random identifier made when the user presses "pay". If the client made a new key for every retry, the protection would vanish.
Common mistake
Retrying every error. A 400 will fail the same way forever, so the retry only adds load. Retry 5xx and timeouts, with a growing pause, and only when the call is idempotent or carries a key. Level 8 covers retries in full.
Check yourself:
- A client receives 403. Should it retry the same request?
- Why must the idempotency key be created before the first attempt?