HTTP Status Codes Explained
5 min read · Web APIs
What are HTTP status codes?
Every HTTP response includes a three-digit status code that tells the client what happened with the request. Status codes are grouped into five classes based on their first digit. Knowing them is essential for building and debugging web applications and APIs.
1xx — Informational
The server has received the request headers and the client should proceed to send the body.
The server is switching protocols as requested by the client (e.g., upgrading to WebSocket).
2xx — Success
Standard success response. The request was successful.
A new resource was successfully created. Typically returned after POST requests.
The request was successful but there is no content to return. Common for DELETE requests.
The server is returning only part of the resource (used for resumable downloads).
3xx — Redirection
The resource has permanently moved to a new URL. Browsers and search engines update their links.
Temporary redirect. The resource is temporarily at a different URL.
The cached version is still valid. The browser can use its cached copy.
Like 302 but guarantees the HTTP method will not change on the redirected request.
Like 301 but guarantees the HTTP method will not change.
4xx — Client Errors
The server cannot process the request due to invalid syntax or missing parameters.
Authentication is required. The client must provide valid credentials.
The client is authenticated but does not have permission to access this resource.
The requested resource does not exist on the server.
The HTTP method used is not supported for this endpoint (e.g., POST on a read-only route).
The request conflicts with the current state of the resource (e.g., duplicate entry).
The resource existed but has been permanently deleted.
The request is well-formed but contains semantic errors (common in REST APIs for validation failures).
The client has sent too many requests in a given time (rate limiting).
5xx — Server Errors
A generic server error. Something went wrong on the server side.
The server does not support the functionality required to fulfill the request.
The server acting as a gateway received an invalid response from an upstream server.
The server is temporarily unable to handle requests (overloaded or down for maintenance).
The server acting as a gateway did not receive a timely response from an upstream server.
401 vs 403 — what's the difference?
This is one of the most common points of confusion:
- 401 Unauthorized — the user is not logged in (not authenticated). They need to provide credentials.
- 403 Forbidden — the user is logged in but does not have permission (not authorized). They are authenticated but not allowed.
Best practices for REST APIs
- Return 200 for successful GET requests
- Return 201 when a resource is created (POST)
- Return 204 for successful DELETE with no body
- Return 400 for invalid input, not 500
- Return 422 for validation errors with details in the body
- Return 429 with a
Retry-Afterheader when rate limiting - Never return 200 with an error in the body — use the right status code
Full HTTP status code reference
Browse all HTTP status codes with descriptions, categories, and use cases.
HTTP Status Codes →