The five classes
The first digit of a status code tells you what kind of answer it is. A client that meets a code it doesn’t know treats it like the x00 code of its class, so an unknown 4xx is handled like a 400.
- 1xx Informational. An interim answer: “carry on” (100), “switching to WebSocket” (101) or “start loading these files” (103). A final response always follows.
- 2xx Success. It worked. 200 is the everyday one, with 201 for something created and 204 when there’s nothing to send back.
- 3xx Redirection. Look elsewhere (the
Locationheader says where), or use your cached copy (304). - 4xx Client error. Something about the request is wrong: the address, the login, the data or how often you’re asking. Sending the same request again won’t help, apart from timing problems like 429.
- 5xx Server error. The request may have been fine, but the server or something behind it failed. Trying again later often works.
The codes you’ll see most
| Code | Name | In short |
|---|---|---|
200 | OK | The request worked and the response contains the result. |
201 | Created | The request worked and created something new, usually found at the URL in the Location header. |
204 | No Content | The request worked and there is nothing to send back. |
301 | Moved Permanently | The page has moved for good to the URL in the Location header. |
302 | Found | The page is temporarily at the URL in the Location header. |
304 | Not Modified | Your cached copy is still up to date, so use that. |
400 | Bad Request | The server can’t or won’t handle the request because something in it is malformed. |
401 | Unauthorized | You need to log in, or the credentials you sent are missing, wrong or expired. |
403 | Forbidden | The server understood who you are and won’t let you do this. |
404 | Not Found | There’s nothing at this URL, or the server won’t say whether there is. |
409 | Conflict | The request clashes with the current state of the resource, such as an edit conflict or a duplicate. |
422 | Unprocessable Content | The request is well formed, but the data in it doesn’t make sense, such as failing validation. |
429 | Too Many Requests | You’ve sent too many requests in a given time. Slow down and try again later. |
500 | Internal Server Error | Something went wrong on the server, and it has no more specific code to describe it. |
502 | Bad Gateway | A proxy or load balancer got an invalid response, or none at all, from the server behind it. |
503 | Service Unavailable | The server can’t handle the request right now, usually because it’s overloaded or down for maintenance. |
504 | Gateway Timeout | A proxy or load balancer gave up waiting for the server behind it to reply. |
401 or 403?
The names are confusing. 401 Unauthorized really means unauthenticated: the server doesn’t know who you are, because the token or password is missing, wrong or expired. It has to send a WWW-Authenticate header saying how to log in. 403 Forbidden means the server knows who you are, or doesn’t care, and the answer is still no. If logging in again could fix it, use 401. If it couldn’t, use 403. If you’d rather not admit the thing exists at all, 404 is allowed too.
301, 302, 307 or 308?
Two questions decide it: is the move permanent, and must the method be kept?
| May change POST to GET | Keeps method and body | |
|---|---|---|
| Permanent | 301 Moved Permanently | 308 Permanent Redirect |
| Temporary | 302 Found | 307 Temporary Redirect |
For ordinary page visits they behave the same, so the choice is really permanent (search engines move to the new URL, browsers cache it) or temporary. After a form submission, use 303 See Other, which always switches to GET so a refresh doesn’t send the form twice.
502, 503 or 504?
All three usually come from a proxy, load balancer or CDN in front of the real application.
- 502 Bad Gateway: the app answered badly or not at all. It crashed, isn’t running, or refused the connection.
- 503 Service Unavailable: the service says it can’t take requests right now, because of maintenance or overload. A
Retry-Afterheader can say when to come back. - 504 Gateway Timeout: the app is running but didn’t reply before the proxy gave up waiting.
Behind Cloudflare, you’ll see its own versions with more detail: 521 (connection refused), 522 (couldn’t connect in time) and 524 (connected, but no response in time).
Picking the right code for an API
- Be specific where it helps the client act:
201with aLocationafter creating,204when there’s no body,202when work is queued. - Never send
200with an error inside. Caches, monitoring, browsers and retry logic all trust the status code. - Use
4xxfor anything the caller can fix, and5xxonly when your side failed. Your alerts will thank you. - Put the detail in the body, ideally in the standard “problem details” format (
application/problem+json, RFC 9457), with a message a person can read. - Use
429withRetry-Afterfor rate limits, so well-behaved clients slow down by themselves.
Debugging an API call? The JWT decoder explains most 401s, the JSON formatter finds the broken JSON behind many 400s, and the URL decoder takes apart long URLs.
The definitions come from RFC 9110, section 15, the RFCs that added later codes, and the IANA status code registry. Unofficial codes link to the documentation of the software that uses them.