HTTP Status Codes: A Developer's Quick Reference
Try HTTP Status Codes Reference free →
The problem
You are debugging an API call and get a 422. Or a 403. Or a 502. You know it is an error, but what exactly does it mean? And when you are building an API yourself, should a missing resource return 400 or 404? Should a validation failure be 400 or 422? Should a login failure be 401 or 403?
HTTP has over 60 status codes. You use maybe 15 of them regularly, but the exact meanings blur together — especially the ones that sound similar, like 301 vs 302 or 401 vs 403.
The codes you actually need to know
Success (2xx)
| Code | Name | When to use |
|---|---|---|
| 200 | OK | The request worked. Default success response. |
| 201 | Created | A new resource was created (POST requests). |
| 204 | No Content | Success, but nothing to return (DELETE requests). |
Redirects (3xx)
| Code | Name | When to use |
|---|---|---|
| 301 | Moved Permanently | The URL has changed forever. Browsers and search engines update their records. Use for domain migrations and permanent URL changes. |
| 302 | Found (Temporary) | The resource is temporarily at a different URL. The original URL is still valid. Use for maintenance redirects or A/B tests. |
| 304 | Not Modified | The cached version is still valid. Saves bandwidth. |
The 301 vs 302 confusion: Use 301 when the old URL should never be used again — search engines will transfer SEO value to the new URL. Use 302 when the redirect is temporary and the old URL will come back. Using 302 when you mean 301 means search engines keep indexing the old URL.
Client errors (4xx)
| Code | Name | When to use |
|---|---|---|
| 400 | Bad Request | The request is malformed — invalid JSON, missing required fields, wrong data type. |
| 401 | Unauthorized | No valid credentials provided. The user is not logged in. |
| 403 | Forbidden | Credentials are valid, but the user does not have permission for this action. |
| 404 | Not Found | The resource does not exist at this URL. |
| 409 | Conflict | The request conflicts with current state (e.g., duplicate username). |
| 422 | Unprocessable Entity | The request is well-formed but fails validation (e.g., email format invalid). |
| 429 | Too Many Requests | Rate limit exceeded. Include a Retry-After header. |
The 401 vs 403 confusion: 401 means "who are you?" — the request has no authentication or the token is expired. 403 means "I know who you are, but you can't do this" — the user is authenticated but lacks permission.
Server errors (5xx)
| Code | Name | When to use |
|---|---|---|
| 500 | Internal Server Error | Something broke on the server. The generic "our fault" error. |
| 502 | Bad Gateway | A proxy or load balancer got an invalid response from the upstream server. |
| 503 | Service Unavailable | The server is overloaded or down for maintenance. |
| 504 | Gateway Timeout | The upstream server did not respond in time. |
Why I built it
I look up HTTP status codes constantly — both when debugging and when deciding which code my API should return. A searchable reference that explains the practical differences (not just the RFC definitions) is the tool I wanted on my own bookmarks bar.