What Are HTTP Status Codes?
HTTP status codes are three-digit numbers returned by web servers in response to a client's request. They indicate whether the request was successful, redirected, resulted in an error, or requires further action. Understanding these codes is essential for debugging, API development, and web application troubleshooting.
Status Code Categories
Request received, continuing process. Rarely seen in practice.
Request was received, understood, and accepted.
Further action needed to complete the request.
Request contains bad syntax or cannot be fulfilled.
Server failed to fulfill a valid request.
2xx Success Codes
Standard success response. The request succeeded and the response body contains the result.
Request succeeded and a new resource was created. Typically returned after POST requests. Should include a Location header with the new resource's URL.
Request accepted but not yet processed. Used for asynchronous operations—processing will happen later.
Request succeeded but there's no content to return. Common for successful DELETE requests or updates where no body is needed.
Server is delivering only part of the resource due to a Range header. Used for resumable downloads and video streaming.
3xx Redirection Codes
Resource has permanently moved to a new URL. Browsers and search engines should update their links. Important for SEO when changing URLs.
Resource temporarily at a different URL. The client should continue using the original URL for future requests.
Response to the request can be found at another URL using GET. Often used after POST to redirect to a confirmation page.
Resource hasn't changed since the last request. The client can use its cached version. Used with conditional GET requests.
Like 302, but guarantees the HTTP method won't change. POST stays POST (unlike 302 which may convert to GET).
Like 301, but guarantees the HTTP method won't change. Newer and stricter than 301.
4xx Client Error Codes
Server cannot process the request due to client error. Could be malformed syntax, invalid request framing, or invalid request parameters.
Authentication is required and has failed or not been provided. Should include a WWW-Authenticate header indicating how to authenticate.
Server understood the request but refuses to authorize it. Unlike 401, authentication won't help—you don't have permission.
Requested resource doesn't exist. The most common error code encountered by users.
HTTP method (GET, POST, etc.) is not supported for this resource. For example, trying to POST to a read-only endpoint.
Server timed out waiting for the request. The client can retry the same request.
Request conflicts with current state of the resource. Often used for edit conflicts or duplicate entries.
Resource existed but has been permanently deleted. Unlike 404, this indicates the resource is intentionally gone.
Request was well-formed but contains semantic errors. Often used for validation failures in APIs.
Rate limit exceeded. Should include Retry-After header indicating when to retry.
5xx Server Error Codes
Generic server error when no more specific message is available. Usually indicates a bug or unhandled exception in the server code.
Server doesn't recognize the request method or can't fulfill it. Unlike 405, implies server doesn't support this functionality at all.
Server acting as a gateway received an invalid response from the upstream server. Common with reverse proxies and load balancers.
Server is temporarily unable to handle the request. Usually due to maintenance or overload. Should include Retry-After header.
Server acting as a gateway didn't receive a timely response from the upstream server.
API Design Best Practices
// Common REST API patterns
GET /users → 200 OK (with user list)
GET /users/123 → 200 OK or 404 Not Found
POST /users → 201 Created (with Location header)
PUT /users/123 → 200 OK or 204 No Content
PATCH /users/123 → 200 OK or 204 No Content
DELETE /users/123 → 204 No Content or 200 OK
// Validation error
POST /users (invalid data) → 422 Unprocessable Entity
{
"errors": {
"email": ["Invalid email format"],
"name": ["Name is required"]
}
}
// Authentication/Authorization
GET /admin (no token) → 401 Unauthorized
GET /admin (valid token, → 403 Forbidden
no permission)
401 vs 403: The Distinction
- "Who are you?"
- No credentials provided
- Invalid credentials
- Expired token
- Try logging in
- "I know who you are, but no"
- Valid credentials
- Insufficient permissions
- Re-authenticating won't help
- Contact admin for access
Quick Reference
- 200: Success with response body
- 201: Created new resource
- 204: Success, no content to return
- 301: Permanently moved (update bookmarks)
- 302/307: Temporarily moved
- 304: Use your cached version
- 400: Bad request syntax
- 401: Login required
- 403: Access denied
- 404: Resource not found
- 422: Validation failed
- 429: Rate limited
- 500: Server crashed
- 503: Server temporarily unavailable
Test Your API Responses
Use our JSON formatter to inspect and validate API response bodies.
Open JSON Formatter →