Three digits that tell you where to look
Every HTTP response begins with a three-digit status code. Before you read a single line of the body, it tells you how the request went, and, when something failed, whose problem it is.
The first digit gives the family:
| Range | Meaning | In short |
|---|---|---|
| 2xx | Success | It worked |
| 3xx | Redirection | Look somewhere else |
| 4xx | Client error | You sent something wrong |
| 5xx | Server error | They failed, though your request was fine |
Most of the time you see 200 OK and think nothing of it. This page is about the nine you will meet when things go wrong, sorted by who has to fix it.
Pick a code and step through the exchange that produces it.
Your side: the 4xx codes
A 4xx means the server looked at your request and declined it. Sending the same request again will give the same answer. Change something first.
400 Bad Request
The request could not be understood: malformed JSON, a missing required field, a value of the wrong type. Read the response body. A good API says exactly what was wrong.
401 Unauthorized
"I do not know who you are." No credentials were sent, or they are invalid or expired. The name is misleading: it is about identity, not permission.
Fix: log in, or refresh the token, and send it again.
403 Forbidden
"I know who you are, and the answer is no." You are identified, and you do not have permission.
Fix: logging in again will not help. You need a different role, or you are asking for something you should not.
Example
401 or 403?
You try to open the staff door of a shop.
401: "Who are you? Show me a badge."
403: "I can see your badge. Customers are not allowed back here."
404 Not Found
Nothing lives at that address. A typo in the path, an id that does not exist, or a record that was deleted. Some servers return 404 in place of 403 on purpose, so as not to reveal that a hidden thing exists.
429 Too Many Requests
Each request was fine. There were just too many. A rate limiter turned you away.
Fix: slow down. Look for a Retry-After header saying how long to wait. See Rate Limiting.
Their side: the 5xx codes from the server
A 5xx means your request was acceptable and the failure happened on the other end.
500 Internal Server Error
The catch-all for "something broke in our code": an unhandled exception, a bug, a failed query. The response usually says little, for safety. The real explanation is in the server's logs.
If it is your server, that is where to look. If it is someone else's, there is nothing to fix on your side.
503 Service Unavailable
"Not right now." The server is overloaded, restarting or down for maintenance. Unlike a 500, this is explicitly temporary.
Fix: retry after a pause, and make the pause longer each time. See Retries, Backoff and Jitter.
In between: the gateway codes
Your request seldom goes straight to the application. It passes through a gateway: a load balancer, reverse proxy or CDN that forwards it to a server behind. Two codes are produced by that middle layer, about the server behind it.
502 Bad Gateway
The gateway forwarded your request and got back something unusable: a refused connection, a reset, or a garbled reply. Usually the application behind it has crashed or is not running.
504 Gateway Timeout
The gateway forwarded your request and waited. The server did not answer within the gateway's time limit. Usually the application is alive but too slow: a long query, or it is itself waiting on something.
Example
502 or 504?
You ask a receptionist to fetch someone from the back office.
502: "I knocked. Nobody is in there."
504: "They said 'one moment' twenty minutes ago and I have given up waiting."
In both cases the gateway is fine and so is your request. Look at the service behind the gateway.
All nine, by who fixes it
| Code | Name | Who fixes it | Retry the same request? |
|---|---|---|---|
| 400 | Bad Request | You | No: fix the request |
| 401 | Unauthorized | You | After logging in |
| 403 | Forbidden | You | No: you lack permission |
| 404 | Not Found | You | No: check the address |
| 429 | Too Many Requests | You | Yes, after waiting |
| 500 | Internal Server Error | The server's owner | Rarely helps |
| 503 | Service Unavailable | The server's owner | Yes, after a pause |
| 502 | Bad Gateway | Whoever runs the service behind the gateway | Maybe, after a pause |
| 504 | Gateway Timeout | Whoever runs the service behind the gateway | Careful: the first attempt may still be running |
Key takeaways
- The first digit says who is responsible: 4xx is the client, 5xx is the server.
- 401 means you are not identified. 403 means you are identified and not allowed.
- 429 means slow down. 503 means try again later. Both are worth retrying after a wait.
- 500 is a failure inside the server, and the details are in its logs.
- 502 and 504 come from a gateway reporting on the server behind it: no usable answer, or no answer in time.