In this article
Every time a browser or app asks a server for something, the server answers with a three-digit number before it sends anything else. That number is the status code. It is the shortest honest summary of what just happened.
The five families
If you can only remember one thing, remember that 4 and 5 split the blame between asker and answerer.
The dozen you will meet
| Code | Name | What it really means |
|---|---|---|
| 200 | OK | Request worked and here is the result |
| 201 | Created | Something new was made, such as a new record |
| 204 | No Content | Worked, with nothing to send back |
| 301 | Moved Permanently | This address is gone for good. Update your links |
| 302 | Found | Temporarily elsewhere. Keep using the old address |
| 304 | Not Modified | Nothing changed, use your cached copy |
| 400 | Bad Request | The request was malformed |
| 401 | Unauthorized | You are not logged in or the credentials are wrong |
| 403 | Forbidden | Logged in, but not allowed |
| 404 | Not Found | Nothing lives at this address |
| 429 | Too Many Requests | Slow down: you hit a rate limit |
| 500 | Internal Server Error | The server crashed handling a good request |
| 503 | Service Unavailable | Overloaded or down for maintenance |
Names follow the standard. “Unauthorized” is a historic misnomer: it really means unauthenticated.
Tell them apart
Mixing up 301 and 302 is a classic SEO mistake. A temporary redirect does not hand over the old page's standing in the same way.
502, 503, 504: the gateway trio
- 1YouSend a request to the website
- 2Front door (proxy or load balancer)Passes it to the real application
- 3The applicationDoes the work, or fails to
Each of these three codes is the front door telling you what it saw happen to the application.
- 502 Bad Gateway: the front door got a broken or invalid answer from the app.
- 503 Service Unavailable: the app is too busy or switched off on purpose. Try again soon.
- 504 Gateway Timeout: the app took too long, so the front door gave up waiting.
For people who build things
- Use the right code. A wrong password is 401, not 200 with an error message inside.
- Do not send 200 for failures. Monitoring tools and caches read the code, not your message.
- Be honest about 404 and 410. 410 Gone tells search engines the page was removed on purpose.
- Return 429 with a Retry-After header so clients know when to try again.
Questions people ask
What do the first digits of HTTP status codes mean?
1xx informational, 2xx success, 3xx redirection, 4xx client error and 5xx server error.
What is the difference between 401 and 403?
401 means you are not authenticated: log in or send valid credentials. 403 means you are authenticated but not permitted to do this.
What is the difference between 301 and 302?
301 is a permanent move and passes the old page's standing to the new one. 302 is a temporary redirect, and the original address stays the main one.
What causes a 502, 503 or 504 error?
502 means the gateway got a bad response from the app, 503 means the app is overloaded or down, and 504 means the app took too long to answer.
Should an API return 200 for errors?
No. Use the appropriate 4xx or 5xx code so clients, caches and monitoring can tell that something failed.