HTTP Status Codes Reference
Complete guide to HTTP status codes from 1xx to 5xx with examples, use cases, and best practices.
Overview
Request received, continuing process.
Request successfully received, understood, and accepted.
Further action must be taken to complete the request.
Request contains bad syntax or cannot be fulfilled.
Server failed to fulfill an apparently valid request.
1xx - Informational Responses
The server has received the request headers and the client should proceed to send the request body.
Use Case
When uploading large files, client can check if server will accept the request before sending the body.
Server is switching protocols as requested by the client (e.g., upgrading to WebSocket).
Use Case
WebSocket handshake, HTTP/2 upgrade.
2xx - Success
Standard response for successful HTTP requests. The actual response depends on the request method.
Use Cases
- • GET: Resource retrieved and returned in response body
- • PUT/PATCH: Resource updated successfully
- • POST: Action completed (when not creating a resource)
Request succeeded and a new resource was created. Should include Location header with URL of new resource.
Use Case
POST requests that create new resources.
Request accepted for processing, but processing has not completed. Used for asynchronous operations.
Use Cases
- • Background job processing
- • Batch operations
- • Long-running tasks
Request succeeded but there is no content to return. No response body should be sent.
Use Cases
- • DELETE requests (resource successfully deleted)
- • PUT/PATCH when no response data needed
- • Actions that don't need to return data
Server is delivering only part of the resource due to a range request from the client.
Use Cases
- • Video streaming (resumable downloads)
- • Large file downloads
- • Bandwidth optimization
3xx - Redirection
Resource has been permanently moved to a new URL. All future requests should use the new URL.
Use Cases
- • URL restructuring
- • Domain changes
- • SEO-friendly redirects
Resource temporarily located at a different URL. Future requests should still use the original URL.
Use Cases
- • Temporary redirects
- • A/B testing
- • Maintenance mode redirects
Resource has not been modified since last requested. Client can use cached version.
Use Cases
- • Conditional GET requests
- • Browser caching
- • Bandwidth optimization
Temporary redirect, but request method must not change (unlike 302 which allows method change).
Use Case
When you need to preserve the HTTP method during redirect (e.g., POST should remain POST).
Permanent redirect where request method and body must not change (unlike 301).
Use Case
Permanent URL changes where HTTP method preservation is required.
4xx - Client Errors
Server cannot process the request due to malformed syntax, invalid data, or other client error.
Use Cases
- • Invalid JSON syntax
- • Missing required parameters
- • Malformed request data
Authentication is required and has failed or not been provided. Should include WWW-Authenticate header.
Use Cases
- • Missing authentication token
- • Invalid or expired token
- • Invalid credentials
Server understood request but refuses to authorize it. Different from 401 - authentication won't help.
Use Cases
- • Insufficient permissions
- • Access to forbidden resource
- • IP blocking
Requested resource could not be found. Most commonly used error code.
Use Cases
- • Resource doesn't exist
- • Invalid endpoint
- • Deleted resource
HTTP method is not supported for the requested resource. Should include Allow header.
Use Case
Client uses wrong HTTP method (e.g., POST when only GET is allowed).
Request conflicts with current state of the server. Often used for duplicate resources or version conflicts.
Use Cases
- • Duplicate email/username
- • Version conflicts
- • Business rule violations
Request was well-formed but contains semantic errors. Used for validation failures.
Use Cases
- • Validation errors
- • Invalid field values
- • Business logic failures
User has sent too many requests in a given time period. Should include Retry-After header.
Use Cases
- • Rate limiting enforcement
- • DDoS protection
- • API quota exceeded
5xx - Server Errors
Generic error when server encounters an unexpected condition. Never expose internal error details to clients.
Use Cases
- • Unhandled exceptions
- • Database errors
- • Any unexpected server error
Server acting as gateway received invalid response from upstream server.
Use Cases
- • Upstream service down
- • Invalid response from proxy
- • Load balancer issues
Server is temporarily unavailable (maintenance, overloaded). Should include Retry-After header.
Use Cases
- • Scheduled maintenance
- • Server overload
- • Temporary shutdown
Server acting as gateway did not receive timely response from upstream server.
Use Cases
- • Upstream timeout
- • Slow database queries
- • Network issues
Quick Reference Table
| Code | Name | When to Use |
|---|---|---|
| 200 | OK | Successful GET, PUT, PATCH |
| 201 | Created | Resource created (POST) |
| 202 | Accepted | Async processing started |
| 204 | No Content | Successful DELETE, no response needed |
| 301 | Moved Permanently | Permanent URL change |
| 302 | Found | Temporary redirect |
| 304 | Not Modified | Use cached version |
| 400 | Bad Request | Invalid request syntax |
| 401 | Unauthorized | Authentication required/failed |
| 403 | Forbidden | Insufficient permissions |
| 404 | Not Found | Resource doesn't exist |
| 405 | Method Not Allowed | Wrong HTTP method |
| 409 | Conflict | Duplicate resource, version conflict |
| 422 | Unprocessable Entity | Validation errors |
| 429 | Too Many Requests | Rate limit exceeded |
| 500 | Internal Server Error | Unexpected server error |
| 502 | Bad Gateway | Invalid upstream response |
| 503 | Service Unavailable | Maintenance, overload |
| 504 | Gateway Timeout | Upstream timeout |