HTTP Status Codes Cheat Sheet

Status Code Categories

• 1xx: Informational - Request received, continuing process
• 2xx: Success - The action was successfully received, understood, and accepted
• 3xx: Redirection - Further action must be taken to complete the request
• 4xx: Client Error - The request contains bad syntax or cannot be fulfilled
• 5xx: Server Error - The server failed to fulfill a valid request

1xx Informational

100 Continue

Request headers received, client should send request body.

Use case: Large file uploads where server validates headers first

101 Switching Protocols

Server is switching protocols as requested by the client (e.g., upgrading to WebSocket).

Common with: WebSocket connections, HTTP/2 upgrades

102 Processing

Server has received and is processing the request, but no response is available yet.

Use case: Long-running operations (WebDAV)

2xx Success

200 OK

Standard successful HTTP request response.

Use case: Successful GET, PUT, or POST that doesn't create a resource
Example: GET /api/users returns user list

201 Created

Request succeeded and a new resource was created.

Use case: Successful POST that creates a new resource
Example: POST /api/users creates a new user
Response should include Location header with new resource URL

202 Accepted

Request accepted for processing, but not yet completed.

Use case: Async operations, batch processing
Example: POST /api/reports/generate (will process later)

204 No Content

Request succeeded but returns no content.

Use case: Successful DELETE, PUT updates that don't return data
Example: DELETE /api/users/123 (user deleted successfully)

206 Partial Content

Server is delivering part of the resource due to range header.

Use case: Video streaming, large file downloads with resume support
Headers: Content-Range, Accept-Ranges

3xx Redirection

300 Multiple Choices

Multiple options for the resource (rarely used).

Use case: Content negotiation with multiple representations

301 Moved Permanently

Resource has been permanently moved to a new URL.

Use case: Site restructuring, domain changes
SEO: Passes link equity to new URL
Browsers: Cache the redirect

302 Found (Temporary Redirect)

Resource temporarily located at different URL.

Use case: Temporary redirects, A/B testing
SEO: Does not pass link equity
Browsers: Don't cache (usually)

303 See Other

Response to POST/PUT/DELETE, directs to GET at another URL.

Use case: After form submission, redirect to result page (POST-Redirect-GET pattern)
Example: POST /checkout → 303 → GET /order/12345

304 Not Modified

Resource not modified since last request (conditional GET).

Use case: Browser caching with If-Modified-Since or If-None-Match
Response: No body, saves bandwidth

307 Temporary Redirect

Like 302 but guarantees HTTP method won’t change.

Use case: Temporary redirects that must preserve POST method

308 Permanent Redirect

Like 301 but guarantees HTTP method won’t change.

Use case: Permanent redirects that must preserve POST method

4xx Client Errors

400 Bad Request

Server cannot process request due to client error (malformed syntax).

Use case: Invalid JSON, missing required fields, malformed data
Example: POST /api/users with invalid email format
Response body: Should explain what's wrong

401 Unauthorized

Authentication required or failed.

Use case: Missing or invalid credentials
Headers: WWW-Authenticate (indicates auth method)
Note: Despite name, it means "unauthenticated"

403 Forbidden

Server understood request but refuses to authorize it.

Use case: User authenticated but lacks permissions
Example: Regular user trying to access admin endpoint
Difference from 401: User IS authenticated but NOT authorized

404 Not Found

Requested resource doesn’t exist.

Use case: Invalid URL, deleted resource, incorrect ID
Example: GET /api/users/99999 (user doesn't exist)
Most common error code

405 Method Not Allowed

HTTP method not supported for this resource.

Use case: POST to read-only resource, DELETE on non-deletable item
Headers: Allow (lists supported methods)
Example: POST /api/users (only GET supported)

406 Not Acceptable

Server cannot produce response matching Accept headers.

Use case: Client requests XML but server only provides JSON
Headers: Accept, Content-Type negotiation

408 Request Timeout

Server timed out waiting for request.

Use case: Slow client connections, incomplete requests

409 Conflict

Request conflicts with current state of server.

Use case: Concurrent updates, duplicate entries, version conflicts
Example: Creating user with existing email
Response body: Should explain the conflict

410 Gone

Resource permanently deleted (stronger than 404).

Use case: Intentionally removed resources, expired content
Example: Old API endpoints that were deprecated and removed
SEO: Search engines remove from index

411 Length Required

Content-Length header required but missing.

Use case: POST/PUT requests without Content-Length

412 Precondition Failed

Condition in request headers not met.

Use case: Conditional requests with If-Match, If-None-Match
Example: Optimistic locking with ETags

413 Payload Too Large

Request body larger than server is willing to process.

Use case: File upload exceeds size limit
Configuration: Server max body size settings

414 URI Too Long

Request URI longer than server can process.

Use case: Too many query parameters, extremely long URLs
Workaround: Use POST instead of GET

415 Unsupported Media Type

Request payload in unsupported format.

Use case: Sending XML when only JSON accepted
Headers: Content-Type mismatch

422 Unprocessable Entity

Request well-formed but semantically incorrect.

Use case: Validation errors, business logic failures
Example: Age field has value -5, date in past for future event
Response body: Detailed validation errors

429 Too Many Requests

User has sent too many requests (rate limiting).

Use case: API rate limiting, DDoS protection
Headers: Retry-After (when to retry)
         X-RateLimit-Limit (max requests)
         X-RateLimit-Remaining (requests left)

5xx Server Errors

500 Internal Server Error

Generic server error when no specific code applies.

Use case: Unhandled exceptions, programming errors
Common causes: Database errors, null references, crashes
Response: Don't expose internal error details to clients

501 Not Implemented

Server doesn’t support functionality required to fulfill request.

Use case: Unimplemented HTTP methods, future features
Example: TRACE method not supported

502 Bad Gateway

Server acting as gateway received invalid response from upstream.

Use case: Proxy/load balancer can't reach backend
Common with: Nginx, API gateways, reverse proxies

503 Service Unavailable

Server temporarily unable to handle request.

Use case: Maintenance, overload, temporary downtime
Headers: Retry-After (when service will be available)
Best practice: Return during planned maintenance

504 Gateway Timeout

Gateway/proxy didn’t receive timely response from upstream.

Use case: Backend server too slow, timeouts
Common with: Load balancers, CDNs, API gateways
Troubleshooting: Check backend performance, increase timeout

505 HTTP Version Not Supported

Server doesn’t support HTTP version used in request.

Use case: Using HTTP/3 with HTTP/1.1-only server (rare)

Quick Reference Table

Code	Name	Category	Common Use
200	OK	Success	Standard success response
201	Created	Success	Resource created successfully
204	No Content	Success	Success with no response body
301	Moved Permanently	Redirect	Permanent URL change
302	Found	Redirect	Temporary redirect
304	Not Modified	Redirect	Cached resource still valid
400	Bad Request	Client Error	Malformed request
401	Unauthorized	Client Error	Authentication required
403	Forbidden	Client Error	Insufficient permissions
404	Not Found	Client Error	Resource doesn’t exist
409	Conflict	Client Error	Request conflicts with current state
422	Unprocessable Entity	Client Error	Validation failed
429	Too Many Requests	Client Error	Rate limit exceeded
500	Internal Server Error	Server Error	Generic server error
502	Bad Gateway	Server Error	Invalid upstream response
503	Service Unavailable	Server Error	Temporary downtime
504	Gateway Timeout	Server Error	Upstream timeout

Best Practices

Choosing the Right Status Code

For Successful Operations:

• Use 200 for successful GET, PUT, PATCH
• Use 201 for successful POST that creates a resource
• Use 204 for successful DELETE or updates with no response body
• Use 202 for accepted async operations

For Redirects:

• Use 301 for permanent redirects (SEO friendly)
• Use 302/307 for temporary redirects
• Use 303 after POST to redirect to GET (POST-Redirect-GET pattern)
• Use 304 for conditional requests (caching)

For Client Errors:

• Use 400 for malformed requests
• Use 401 when authentication is required/failed
• Use 403 when user is authenticated but not authorized
• Use 404 when resource doesn’t exist
• Use 422 for validation errors
• Use 429 for rate limiting

For Server Errors:

• Use 500 for unexpected server errors
• Use 502 for gateway/proxy issues
• Use 503 during maintenance or when overloaded
• Use 504 for upstream timeouts

Common Mistakes to Avoid

1. Using 200 for errors - Don’t return 200 with error message in body
2. Confusing 401 and 403 - 401 = not authenticated, 403 = not authorized
3. Overusing 500 - Use specific 4xx codes for client errors
4. Wrong redirect codes - 301 vs 302 matters for SEO
5. Not including error details - Include helpful error messages in response body
6. Inconsistent error format - Use standardized error response structure

Error Response Format

Good error response structure:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid input data",
    "details": [
      {
        "field": "email",
        "message": "Invalid email format"
      },
      {
        "field": "age",
        "message": "Must be between 0 and 120"
      }
    ]
  }
}

Testing Status Codes

Using curl

# Get status code only
curl -s -o /dev/null -w "%{http_code}" https://api.example.com

# Include headers to see status
curl -I https://api.example.com

# Verbose output shows full response
curl -v https://api.example.com

# Test different methods
curl -X POST https://api.example.com/users
curl -X DELETE https://api.example.com/users/123

Testing with httpie

# Clean output with status
http GET https://api.example.com

# See headers only
http --headers GET https://api.example.com

Tips

1. Status codes communicate intent - use them correctly
2. 4xx means client needs to fix something, 5xx means server has a problem
3. Always return appropriate status codes, don’t mask errors with 200
4. Include meaningful error messages in response body
5. Use 401 for authentication issues, 403 for authorization issues
6. Return 201 with Location header when creating resources
7. Use 429 with Retry-After header for rate limiting
8. Return 503 with Retry-After during maintenance
9. Don’t expose sensitive error details to clients (use 500 generically)
10. Log detailed errors server-side while returning safe messages to clients
11. Use 422 for validation errors rather than 400
12. Cache 301 redirects, but be careful - they’re hard to undo