HTTP Status Codes

Five classes, one digit

Every HTTP response carries a three-digit status code, and the first digit tells you which family it belongs to. 1xx is informational, 2xx means success, 3xx signals redirection, 4xx reports a client error, and 5xx reports a server error. Memorising the leading digit of each class is worth far more than learning every individual value.

Reading just that first digit lets your code branch sensibly without keeping a giant lookup table in your head. A 2xx means carry on and process the body; a 4xx means fix the request before trying again; a 5xx means the server stumbled and a retry might well succeed. Start there, then look at the specific code only when you need the detail.

Success and redirection

The everyday success code is 200 OK. Creating a resource often returns 201 Created with a Location header pointing at the new record, while an accepted-but-not-yet-finished job may return 202 Accepted to say work is queued. A call that succeeds but has nothing to send back uses 204 No Content, common after a successful DELETE.

Redirection codes such as 301 and 308 tell you a resource lives at a different address now, and you should follow or update accordingly. 304 Not Modified says your cached copy is still fresh and can be reused. Most HTTP clients follow redirects automatically, but it is worth knowing they happened so an unexpected hop does not puzzle you later when reading logs.

When you got it wrong: 4xx

A 4xx code means the server understood your request but will not fulfil it as sent. The classics are 400 Bad Request for malformed input, 401 Unauthorized when credentials are missing or invalid, 403 Forbidden when you are authenticated but not permitted, and 404 Not Found when the resource simply does not exist at that address.

Two more matter a great deal for integrations: 409 Conflict when the request clashes with the current state, and 429 Too Many Requests when you have hit a rate limit. Retrying most 4xx responses unchanged will fail in exactly the same way — these need a fix to the request itself, not a stubborn repeat. The one exception is 429, which asks you to wait and then try again.

When the server stumbled: 5xx

A 5xx code means your request looked fine but the server could not complete it — 500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable, or 504 Gateway Timeout. Unlike most 4xx responses, these are frequently transient and clear up on their own within seconds.

HTTP/1.1 503 Service Unavailable
Retry-After: 5

The sensible response is to wait and retry with exponential backoff, ideally honouring any Retry-After header the server provides rather than guessing a delay. Restrict automatic retries to safe or idempotent requests, however, so a retried write does not quietly create a duplicate. A blind retry of a non-idempotent POST after a 5xx is a classic way to double-charge or double-create.

Codes first, body second

Always branch on the status code before you attempt to parse the body. A failed call may return a structured error document, an empty payload, or even raw HTML emitted by a proxy that never reached the application — trusting the body without first checking the code leads to confusing, hard-to-trace bugs.

Reading the status line first turns ambiguous failures into clear decisions about what to do next. To turn those error responses into clean, consistent handling logic across your whole integration, read handling API errors, which builds directly on the status-code classes covered here and shows how to act on each one.