HTTP status codes cheat sheet (1xx to 5xx)

What HTTP status codes are

Your checkout page worked fine all morning. Now it shows a blank screen, and the network tab says 422. Was that the browser, your code or the payment API? The status code is the first clue, and it tells you more than you might think.

Every HTTP response starts with a three-digit code saying how the request went. The first digit gives you the class, so you know the rough story before you look up the exact number:

• 1xx: informational, the request is still in progress
• 2xx: success
• 3xx: redirection, the client has to do something else
• 4xx: client error, the request itself is wrong
• 5xx: server error, the request looked fine but the server failed

A handy rule of thumb: 4xx means “you broke it”, 5xx means “they broke it”. The code sits in the status line, the very first line of the response, before the headers:

HTTP/1.1 404 Not Found
Content-Type: application/json

{"error": "Order ord_7Q2K for Priya Nair not found"}

The codes and their meanings are defined in RFC 9110, with a few extras such as 429 (RFC 6585) and 103 (RFC 8297).

1xx informational

Think of a 1xx as the server saying “got it, hang on”. It’s an interim response, and the real one follows on the same connection. Your HTTP client usually deals with these quietly, so you’ll rarely see one in your own code.

2xx success

The happy path. The server got your request, understood it and did what you asked. The exact code tells you a bit more, like whether something new was created or whether there’s a body to read at all.

3xx redirection

The thing you asked for is somewhere else, and the Location header tells you where. It’s like a forwarding address after a move. The redirect codes differ in two ways: is the move permanent, and may the client change the request method when it follows the redirect? That second question is the one people forget.

4xx client errors

The server looked at your request and said no, because something about it is wrong. Sending it again unchanged will get the same answer, so don’t just hit retry. (429 is the exception: wait a bit and it will go through.) If you’re building against an API, you’ll see these more than any other class.

5xx server errors

Your request was probably fine. The server tripped over its own feet: a bug, an outage or too much traffic at once. 502, 503 and 504 often clear up on their own, so retrying after a short delay is reasonable. A 500 that happens every time is a bug, and waiting won’t fix it.

Debugging an unexpected status code

Before you start guessing, read the response body. Most APIs put a plain-English error message there, and it often names the exact field that’s wrong. To see the status line, headers and body in one go, run the request with curl -i:

curl -i https://api.example.com/orders/ord_7Q2K \
  -H "Authorization: Bearer $TOKEN"

Then narrow it down by code:

• 400 or 422: compare your body with the API’s schema and check the Content-Type header.
• 401: check that the token is present, correctly formatted and not expired.
• 403: the credentials work but lack permission for this resource or action.
• 404: check the URL, the API version in the path and the resource ID.
• 429, 502, 503, 504: retry with exponential backoff and respect Retry-After.
• 500: check the server logs, or report it to the API provider with the request details.