Status codes

Topics in this section
2 cards

The status code families

The first digit of a status code is its family (1xx informational responses are rare in APIs), and clients act on it even when they don't know the exact code. 2xx: it worked. 3xx: look elsewhere (a redirect, or 304 Not Modified, 'your cached copy is still good'). 4xx: the client made a mistake; sending the same request again usually won't help (429 is the exception: wait, then retry). 5xx: the server failed; the same request may work later.

That split decides retries. A client should not retry a 400 unchanged, but can retry a 503 after a pause. Returning 200 with {"error": …} in the body breaks this: monitoring counts it as a success, and generic clients won't retry or report it.

The five status families with common codes in each
In real life

Load balancers and API gateways mark a backend unhealthy based on its 5xx rate. An API that returns 200 for every error hides its own outages from them.

Check yourself

Which responses may a client reasonably retry later without changing the request? (Choose two.)

Select 2, then check.

The codes you'll actually use

A small set covers most APIs. 200 OK: success with a body. 201 Created: a POST made a new resource; send its URL in Location. 204 No Content: success with no body, common for DELETE. 202 Accepted: the work was queued, not done yet.

400 Bad Request: a general client error, most often used for a malformed request (broken JSON, wrong type). 422 Unprocessable Content: well-formed, but the values break a rule (end date before start date). 401 Unauthorized: no valid credentials. 403 Forbidden: valid credentials, not allowed. 404 Not Found. 409 Conflict: clashes with the current state (the seat is already booked). 429 Too Many Requests: rate limited.

500: a bug or unexpected failure. 502/504: a gateway got a bad answer or no answer in time from the service behind it. 503: temporarily unavailable.

In real life

Booking the last seat twice: the first POST /bookings gets 201 Created, the second gets 409 Conflict with a message saying the seat is taken.

Check yourself

A client sends a valid token, but the user may only read reports, not delete them. It calls DELETE /reports/5. Which statuses are reasonable? (Choose two.)

Select 2, then check.