HTTP Status Codes Reference Guide
Complete guide to HTTP status codes: 2xx success, 3xx redirects, 4xx client errors, 5xx server errors.
Status Code Categories
1xx - Informational
Request received, processing continues
2xx - Success
Request succeeded, action received/understood
3xx - Redirect
Further action needed to complete request
4xx - Client Error
Request contains error (client responsibility)
5xx - Server Error
Server failed to fulfill valid request
Common Status Codes
2xx Success Status Codes (Detailed)
200 OK
Standard success response. Server processed request successfully and returned data in response body.
201 Created
Resource created successfully. Used in POST requests. Response should include Location header with new resource URL.
202 Accepted
Request accepted for processing but not yet complete. Used for async operations that will complete later.
204 No Content
Request succeeded but no content returned. Common in DELETE operations or updates with no response needed.
206 Partial Content
Server delivers partial content due to byte range request. Used for streaming/resumable downloads.
3xx Redirect Status Codes (Detailed)
300 Multiple Choices
Multiple representations of resource available. Server lists options. Rarely used in modern APIs.
301 Moved Permanently
Resource permanently moved to new URL. Browsers update bookmarks. Old URL should not be used again.
302 Found (Temporary Redirect)
Resource temporarily at different URL. Browsers don't update bookmarks. Expected to move back to original URL.
304 Not Modified
Cached version is valid. Client should use local cache instead of downloading again. Improves performance.
307 Temporary Redirect
Like 302 but preserves HTTP method (POST stays POST). Use for consistent method handling.
4xx Client Error Status Codes (Detailed)
400 Bad Request
Server cannot process request due to client error. Malformed syntax, invalid parameters, or missing required fields. Client should not retry without changes.
401 Unauthorized
Authentication required but not provided or invalid. Client must authenticate (login) to access resource. Not about permissions, but identity.
403 Forbidden
Client is authenticated but doesn't have permission to access. Permissions issue, not authentication. User exists but lacks access rights.
404 Not Found
Resource doesn't exist or endpoint is invalid. Client requested URL that doesn't map to any resource on server.
409 Conflict
Request conflicts with current state (e.g., duplicate entry, version mismatch). Common in concurrent update scenarios.
429 Too Many Requests
Rate limit exceeded. Client sent too many requests in short time. Implement exponential backoff and respect Retry-After header.
5xx Server Error Status Codes (Detailed)
500 Internal Server Error
Generic server error. Unexpected condition occurred. Server failed to fulfill valid request. Clients can retry after delay.
501 Not Implemented
Server doesn't support the functionality required. HTTP method or feature not implemented on this endpoint.
502 Bad Gateway
Invalid response from upstream server. Gateway/proxy received bad response from backend. Often indicates deployment issues.
503 Service Unavailable
Server temporarily unavailable. Usually due to maintenance, overload, or deployment. Include Retry-After header with estimated recovery time.
504 Gateway Timeout
Gateway request timed out. Upstream server took too long to respond. Check service health and database performance.
Choosing the Right Status Code
Data Successfully Created/Modified?
→ 200 (OK) or 201 (Created)
Request Failed Due to Client?
→ 4xx status (400, 401, 403, 404, 429)
Server Error / Unexpected Condition?
→ 5xx status (500, 502, 503, 504)
Redirect Needed?
→ 3xx status (301 permanent, 302 temporary)
Common Mistakes with Status Codes
Returning 200 for errors
Always use appropriate 4xx/5xx codes. HTTP status code is part of the API contract.
Confusing 401 and 403
401 = 'who are you?' (authentication), 403 = 'I know who you are, but NO' (authorization)
Using 500 for validation errors
Validation errors are client mistakes (400 Bad Request), not server errors
Ignoring response codes in client
Always handle different status codes appropriately in API clients
Not setting Cache-Control headers with 304
304 Not Modified requires proper cache headers to work effectively
HTTP Status Code FAQ
Should I retry on 4xx errors?
No. 4xx indicates client error. Retrying won't help unless you fix the request. Only retry on 5xx or 429 (rate limited) with backoff.
What's the difference between 201 and 200?
201 Created signals a new resource was created (usually POST). Include Location header with new resource URL. 200 OK is for other successful operations.
When should I use 202 Accepted?
For long-running operations that are processed asynchronously. Return immediately with 202, let client poll status endpoint for progress.
How do I handle rate limiting (429)?
Return 429 with Retry-After header (in seconds). Client should wait before retrying. Implement exponential backoff to avoid overwhelming server.
Is 404 always safe to cache?
Be careful. 404 can change if resource is created later. Use short cache TTL (minutes) for 404. Permanent 404s can use longer TTL.
Related Concepts
Related Tools
API Rate Limiting Guide
Handle 429 rate limit responses effectively.
CORS Guide
Understand 4xx errors in cross-origin requests.