HTTP Status Codes
Search and understand HTTP response status codes, their categories, and practical guidance.
Common status codes
58 status codes
What is an HTTP status code?
An HTTP status code is the three-digit number a server returns with every response, telling the client whether the request succeeded, was redirected, or failed. The first digit groups the meaning: 1xx informational, 2xx success, 3xx redirection, 4xx client error, 5xx server error.
This reference lists every registered code with its official name and the situation it is meant for, so you can pick the right one when building an API instead of defaulting to 200 or 500.
How to look up a status code
- Type the number (429) or a word from the name (timeout, gateway) into the search box.
- Narrow the list with the 1xx–5xx filter pills if you already know the error class.
- Click a row to open its detail panel, which explains when a server should return it.
- Copy the code with the copy button, or open the MDN page for the full specification.
- Compare adjacent codes before committing — 401 vs 403 and 301 vs 307 are the pairs most often mixed up.
Status code examples
Auth vs permission
GET /admin — no token sent
401 Unauthorized — the client must authenticate first
Rate limiting
100 requests in one second
429 Too Many Requests — add Retry-After and slow down
Commonly confused code pairs
| Dimension | 401 Unauthorized | 403 Forbidden |
|---|---|---|
| Meaning | Credentials missing or invalid | Authenticated but not allowed |
| Retry after login | Yes, usually works | No, permissions must change |
| Typical cause | Expired token | Role missing an entitlement |
| WWW-Authenticate header | Expected | Not required |
HTTP status code FAQ
What is the difference between 401 and 403?
401 means the request has no valid credentials; 403 means the caller is authenticated but not allowed to perform the action.
When should I return 404 instead of 403?
Return 404 when revealing the resource exists would leak information — for example, another tenant private record.
301 or 308 for a permanent redirect?
301 allows the method to change to GET on some clients; 308 preserves the method and body. Use 308 for non-GET endpoints.
Is 200 OK for a failed lookup?
No. Use 404 Not Found so clients and crawlers can react correctly.
What status should a validation error return?
422 Unprocessable Content when the syntax is valid but the semantics fail; 400 Bad Request when the request itself is malformed.
Should I use 500 for expected failures?
No. 5xx signals a server fault that needs attention. Use 4xx for client-caused problems.