HTTP Status Codes Explained: A Practical Guide for API Developers

If you build or consume APIs, HTTP status codes are the vocabulary you use to say what happened. Get them right and your API is a pleasure to integrate with; get them wrong and every client ends up writing fragile guesswork around your responses. Yet a surprising number of APIs still return 200 OK with an error buried in the body. Let us fix that habit.

The five families

Every status code falls into one of five ranges, and knowing the range tells you almost everything:

• 1xx Informational — rare; the request was received and processing continues.
• 2xx Success — the request worked.
• 3xx Redirection — more action is needed, usually following a new location.
• 4xx Client errors — the caller did something wrong.
• 5xx Server errors — you did something wrong.

That 4xx-versus-5xx split matters: it tells the client whether retrying could ever help. Blur it and you break every sensible retry policy on the internet.

The codes you will actually use

You do not need all sixty-odd codes. A great API leans on a small, honest set:

• 200 OK — standard success for reads and updates.
• 201 Created — a POST created a resource; include its URL in the Location header.
• 204 No Content — success with nothing to return, perfect for DELETE.
• 400 Bad Request — the payload is malformed or fails validation.
• 401 Unauthorized — you are not authenticated (misnamed, but that is what it means).
• 403 Forbidden — you are authenticated but not allowed.
• 404 Not Found — the resource does not exist.
• 409 Conflict — the request clashes with current state, like a duplicate signup.
• 422 Unprocessable Entity — well-formed but semantically invalid; a favorite for validation errors.
• 429 Too Many Requests — slow down; pair it with a Retry-After header.
• 500 Internal Server Error — something blew up on your side.
• 503 Service Unavailable — temporarily down or overloaded.

401 vs 403: the one everyone confuses

Use 401 when the client has not proven who they are — a missing or expired token. Use 403 when you know exactly who they are and they still are not allowed near this resource. “Who are you?” versus “I know who you are, and no.” Getting this pair right removes a whole category of confusing support tickets.

Be consistent, and mean it

The worst thing an API can do with HTTP status codes is lie. Do not return 200 with {"error": "not found"}; return 404. Do not return 500 for a validation failure the user caused. When the status line tells the truth, clients can handle errors generically and your logs and dashboards suddenly become meaningful. Consistency here is worth more than cleverness anywhere else in your API.