HTTP Status Codes Guide — Complete Reference with Examples
HTTP status codes are three-digit numbers returned by servers to indicate the result of a request. Understanding them is essential for debugging APIs, configuring CDNs, and building reliable web applications. Look up any status code instantly with our HTTP Status Code Lookup tool.
Status Code Classes
HTTP status codes are grouped into five classes, identified by the first digit:
| Class | Category | Description |
|---|---|---|
| 1xx | Informational | The request was received and is being processed. These are provisional responses with no body. |
| 2xx | Success | The request was received, understood, and accepted successfully. |
| 3xx | Redirection | The client must take additional action to complete the request, usually following a redirect. |
| 4xx | Client Errors | The request contains bad syntax or cannot be fulfilled. These errors are the client's responsibility. |
| 5xx | Server Errors | The server failed to fulfill a valid request. The responsibility lies with the server. |
1xx Informational
These codes indicate the server has received the request and is continuing to process it. They are rarely seen by client applications as they are handled transparently by HTTP libraries.
| Code | Name | Usage |
|---|---|---|
| 100 | Continue | Client should continue sending the request body. Used to avoid sending large payloads before checking server readiness. |
| 101 | Switching Protocols | Server is upgrading to a different protocol (e.g., HTTP to WebSocket). Used during WebSocket handshake. |
| 102 | Processing | Server has received and is processing the request, but no response is available yet. Used for long operations. |
| 103 | Early Hints | Server sends preliminary headers while preparing the full response. Used to preload resources before the final response. |
2xx Success
The most common response class. These codes mean the request was successfully received, understood, and accepted.
| Code | Name | Usage |
|---|---|---|
| 200 | OK | The request succeeded. The meaning depends on the HTTP method: GET returns the resource, POST returns the created resource, PUT/PATCH returns the updated resource. |
| 201 | Created | A new resource was created successfully. Usually returned after POST requests. The Location header contains the URL of the new resource. |
| 202 | Accepted | The request was accepted for processing but is not yet complete. Used for asynchronous operations like batch jobs or report generation. |
| 204 | No Content | The request succeeded but there is no content to return. Commonly used for DELETE operations and PUT/PATCH updates that return no body. |
| 206 | Partial Content | The server is delivering only a portion of the resource. Used for range requests (video streaming, resumable downloads). |
Tip: Always return 201 for resource creation and 204 for deletion. These codes help API consumers understand exactly what happened without reading the response body.
3xx Redirection
The client must take additional action to complete the request. The Location header tells the client where to go next.
| Code | Name | Usage |
|---|---|---|
| 301 | Moved Permanently | The resource has been permanently moved to a new URL. Search engines update their indexes. The old URL should no longer be used. |
| 302 | Found (Temporary Redirect) | The resource is temporarily at a different URL. Search engines keep the old URL. Used for legacy URL forwarding. |
| 303 | See Other | The response is available at another URL via GET. Used after POST to redirect to a confirmation page (POST-Redirect-GET pattern). |
| 304 | Not Modified | The resource has not changed since the last request. Returned for conditional requests with If-None-Match or If-Modified-Since headers. |
| 307 | Temporary Redirect | Like 302 but the HTTP method must not change. If a POST request gets a 307, the client must redirect using POST. |
| 308 | Permanent Redirect | Like 301 but the HTTP method must not change. The same method must be used for the redirected request. |
SEO Note: Use 301 for permanent URL changes so search engines transfer ranking to the new URL. Use 302 or 307 for temporary redirects during maintenance.
4xx Client Errors
These are the most common errors developers encounter. They indicate the client sent an invalid request.
| Code | Name | Usage |
|---|---|---|
| 400 | Bad Request | The server cannot process the request due to invalid syntax, malformed JSON, or missing required fields. The response body usually explains what is wrong. |
| 401 | Unauthorized | Authentication is required. The client must provide valid credentials (e.g., a valid JWT token or API key) in the Authorization header. |
| 403 | Forbidden | The client is authenticated but does not have permission to access the resource. Unlike 401, the client's identity is known. |
| 404 | Not Found | The requested resource does not exist. This is the most famous HTTP status code. Common causes: wrong URL, deleted resource, or mistyped endpoint. |
| 405 | Method Not Allowed | The HTTP method used is not supported for this endpoint. The Allow header lists the permitted methods. |
| 408 | Request Timeout | The server timed out waiting for the client to send the complete request. Common with slow connections or large uploads. |
| 409 | Conflict | The request conflicts with the current state of the server. Common when trying to create a resource that already exists (duplicate entry). |
| 410 | Gone | The requested resource is permanently gone and will not be available again. Unlike 404, the server knows the resource existed but was intentionally removed. |
| 415 | Unsupported Media Type | The request's Content-Type is not supported by the server. Common when sending JSON to an endpoint that expects form data or vice versa. |
| 422 | Unprocessable Content | The request body is syntactically correct but semantically invalid. Used by REST APIs for validation errors (e.g., invalid email format). |
| 429 | Too Many Requests | The client has exceeded the rate limit. The Retry-After header indicates when the client can retry. Essential for public API rate limiting. |
Debugging Tip: When debugging 4xx errors, always check the request headers (Content-Type, Authorization) and the request body format first. Most 400 errors are caused by missing or malformed headers.
5xx Server Errors
These indicate the server failed to fulfill a valid request. Unlike 4xx errors, the problem is on the server side.
| Code | Name | Usage |
|---|---|---|
| 500 | Internal Server Error | A generic error when the server encounters an unexpected condition. The response body usually contains error details in development but should be generic in production. |
| 502 | Bad Gateway | The server, acting as a gateway or proxy, received an invalid response from the upstream server. Common with CDN and reverse proxy configurations. |
| 503 | Service Unavailable | The server is temporarily unable to handle the request due to maintenance or overload. The Retry-After header indicates when to retry. |
| 504 | Gateway Timeout | The server, acting as a gateway, did not receive a timely response from the upstream server. Common when a downstream service is slow or down. |
| 505 | HTTP Version Not Supported | The server does not support the HTTP protocol version used in the request. Rare in modern web applications. |
Monitoring Tip: A sudden spike in 5xx errors usually indicates a deployment issue, database failure, or upstream service outage. Set up alerting for 5xx rates in your monitoring system.
Status Code Best Practices for API Design
Use the correct class
Always return 2xx for success, 4xx for client errors, and 5xx for server errors. Mixing these up confuses API consumers and monitoring tools.
Include meaningful error bodies
Return a JSON body with an error message and code: {"error": "invalid_email", "message": "The email address is not valid."}
Don't expose internals in 5xx
In production, never include stack traces or internal error details in 500 responses. Log the details server-side and return a generic message.
Use 429 for rate limiting
Always include a Retry-After header with 429 responses so clients know when to retry. Use 403 for permission errors, not rate limiting.
Prefer 409 for conflicts
When a create request fails because the resource already exists, return 409 Conflict with details about the existing resource.
Frequently Asked Questions
What is the difference between 401 and 403?
401 means you are not authenticated (logged in). 403 means you are authenticated but do not have permission to access the specific resource.
Should I use 301 or 308 for permanent redirects?
Use 308 if you need to preserve the HTTP method. Use 301 for backward compatibility — some legacy clients handle 301 better than 308.
When should I use 201 vs 200 for POST?
Use 201 when a new resource is created. Use 200 when the POST operation updates or processes without creating a new resource.
Is 404 always a mistake?
Not necessarily. Some APIs return 404 instead of 403 to avoid revealing the existence of resources to unauthorized users.