HTTP Status Code

TL;DR: An HTTP status code is the three-digit number in every response that says how the request went. The first digit is the class: 1xx informational, 2xx success, 3xx redirect, 4xx client error, 5xx server error. Read it with the method and headers; a 5xx on a write doesn’t tell you whether a retry is safe.

The Five Classes

RFC 9110 §15 defines the classes:

• 1xx: informational response during the exchange.
• 2xx: the request was received, understood and accepted.
• 3xx: further action is needed, such as a redirect or cache validation.
• 4xx: the request looks like it has a client error.
• 5xx: the server failed to fulfill an apparently valid request.

The class is where diagnosis starts, not where it ends. A 4xx can come from a server misconfiguration, and a write may have landed before a 5xx.

Why Status Codes Matter

Clients use the status to decide what to do next: follow a redirect, ask for credentials, reuse a stored representation, or show an error. A client that gets an unknown code treats it like the x00 code of its class, except that it must not cache the response. So a client that has never seen 471 handles it like 400, without guessing what the last two digits mean.

Common Examples

200 means success, in the sense the method defines. 201 means something was created. 202 means accepted but not finished. 204 forbids response content. 304 answers a conditional GET or HEAD without content; the client uses its stored copy.

401 means the request lacks valid credentials, and it must carry a WWW-Authenticate challenge. 403 means the server understood the request and refuses it, whether or not it knows who you are. 404 means no current representation, or the server won’t say whether one exists. 500 reports an unexpected server condition.

The Human Way To Read Them

Look at the headers, not just the status:

curl -i 'https://api.example.com/documents/notes'

A 405 should come with Allow. A 401 should come with a challenge. A 412 on a conditional write means your precondition failed. For a 202, check the API’s status URL before treating the job as done.

A Common Mistake

Fetch doesn’t reject on a 404 or 500. Check it yourself:

const response = await fetch('/api/documents/notes')
if (!response.ok) throw new Error(`HTTP ${response.status}`)

Be selective about retrying 5xx responses. If the server committed a POST and then failed while sending the result, a retry runs the action twice. Whether a retry is safe depends on the method and the API’s deduplication contract as much as the status.

Related

• HTTP Response
• Idempotent