HTTP Status Codes Cheat Sheet: Complete REST API Response Reference & Debugging Guide
Master HTTP status codes (1xx, 2xx, 3xx, 4xx, 5xx) with this comprehensive REST API response guide. Learn RFC specifications, header requirements, common causes, and step-by-step debugging fixes.
Every HTTP request initiated by a web browser, mobile app, API client, or microservice receives an HTTP response status code from the server. Standardized by the Internet Engineering Task Force (IETF) in RFC 9110 (HTTP Semantics), these 3-digit status codes communicate the status of a request—whether it succeeded, required redirection, encountered client-side validation errors, or triggered a server-side crash.
Correctly choosing and handling HTTP status codes is fundamental to building clean RESTful APIs, optimizing browser caching strategies, preventing security vulnerabilities, and ensuring search engines properly crawl and index your web pages. This guide provides an authoritative reference cheat sheet covering every standard HTTP status code across all 5 classes, accompanied by real-world REST API design patterns and debugging solutions.
1. The 5 Classes of HTTP Status Codes
The first digit of an HTTP status code defines its response class. The HTTP protocol categorizes status codes into five distinct ranges:
| Code Range | Category Class | Meaning & Purpose |
|---|---|---|
| 1xx | Informational | Request received and protocol handshakes processing (interim response). |
| 2xx | Success | The client request was successfully received, understood, and accepted. |
| 3xx | Redirection | Further action is required by the client to complete the request (URL relocation or cache validation). |
| 4xx | Client Error | The request contains bad syntax, missing credentials, invalid parameters, or unauthorized access. |
| 5xx | Server Error | The server failed to fulfill an apparently valid request due to internal failure, crash, or gateway timeout. |
2. 1xx Informational Status Codes
1xx codes indicate an interim response while the server processes protocol upgrades or large payload transfers.
- 100 Continue: Indicates that the server has received the request headers and the client should proceed to send the request body (used in Expect: 100-continue headers for large file uploads).
- 101 Switching Protocols: Sent in response to an Upgrade request header when upgrading connections to WebSockets (ws:// or wss://) or HTTP/2.
- 102 Processing (WebDAV): Indicates that the server has accepted the request but has not yet completed execution.
- 103 Early Hints: Allows the server to return HTTP headers (such as Link rel=preload) before the full response body is generated, accelerating browser asset loading.
3. 2xx Success Status Codes
2xx codes indicate that the server processed the request without errors.
| Status Code | Name | API Usage & Best Practice Description |
|---|---|---|
| 200 OK | Standard Success | Standard response for successful GET, PUT, PATCH, or POST requests returning data payloads. |
| 201 Created | Resource Created | Returned after POST requests create a new resource. Should include a Location response header pointing to the new URI. |
| 202 Accepted | Async Processing | Indicates request has been accepted for background processing (e.g. queue worker), but execution is not yet complete. |
| 204 No Content | Empty Success | Indicates successful request completion without returning a response body (commonly used for DELETE or PUT operations). |
| 206 Partial Content | Range Download | Sent when fulfilling HTTP Range request headers (used for streaming video/audio and chunked file downloads). |
4. 3xx Redirection Status Codes
3xx codes instruct the client (browser or curl) to fetch the requested resource from a different location or leverage browser cache.
| Status Code | Name | Behavior & SEO Implication |
|---|---|---|
| 301 Moved Permanently | Permanent Redirect | Target URI has changed permanently. Search engines transfer 90-99% of PageRank link equity to the new location. |
| 302 Found | Temporary Redirect | Target URI has changed temporarily. Search engines retain indexing on original URL. |
| 304 Not Modified | Conditional Cache | Indicates resource has not changed since last fetch (validated via ETag or If-Modified-Since headers). No body is sent. |
| 307 Temporary Redirect | Method Preserving Temp | Guarantees that HTTP request method (POST, PUT) and request body will NOT be changed to GET upon redirect. |
| 308 Permanent Redirect | Method Preserving Perm | Guarantees that HTTP request method (POST, PUT) will NOT be changed to GET on permanent redirect. |
5. 4xx Client Error Status Codes
4xx codes indicate that the client submitted invalid parameters, missing headers, unauthenticated credentials, or non-existent endpoints.
| Code | Status Name | Root Cause & Resolution |
|---|---|---|
| 400 | Bad Request | Malformed JSON syntax, invalid request payload structure, or missing required fields. |
| 401 | Unauthorized | Authentication is required or credentials (JWT/API Key) are invalid or expired. Server MUST include WWW-Authenticate header. |
| 403 | Forbidden | Authentication recognized, but authenticated user lacks sufficient RBAC permission/role to access resource. |
| 404 | Not Found | Requested URI path does not exist on server or route handler was not matched. |
| 405 | Method Not Allowed | HTTP verb (e.g. POST) is not supported on endpoint. Server MUST return Allow header listing valid verbs (GET, OPTIONS). |
| 408 | Request Timeout | Server timed out waiting for client to complete sending HTTP request body. |
| 409 | Conflict | Request conflicts with current server state (e.g. duplicate unique email registration or database optimistic lock). |
| 413 | Payload Too Large | Request body exceeds server upload limits (e.g. Nginx client_max_body_size). |
| 415 | Unsupported Media Type | Content-Type request header (e.g. text/plain) is not supported by endpoint expecting application/json. |
| 422 | Unprocessable Entity | Request body is syntactically valid JSON, but fails schema validation (e.g. string length, regex format). |
| 429 | Too Many Requests | Client has exceeded rate limits. Server should include Retry-After header indicating wait duration. |
6. 5xx Server Error Status Codes
5xx codes indicate an unhandled runtime error, infrastructure outage, or gateway failure on the server.
| Code | Status Name | Server Diagnosis & Fix |
|---|---|---|
| 500 | Internal Server Error | Unhandled exception or crash in application backend code. Check server application logs. |
| 501 | Not Implemented | Server does not support functionality required to fulfill request (e.g. unsupported HTTP method). |
| 502 | Bad Gateway | Reverse proxy (Nginx, Cloudflare) received an invalid response or connection refusal from backend app server (Node, Gunicorn). |
| 503 | Service Unavailable | Server is temporarily down due to overload, maintenance, or connection pool exhaustion. Include Retry-After header. |
| 504 | Gateway Timeout | Reverse proxy timed out waiting for upstream backend or database query to finish. |
7. REST API Best Practices: Mapping HTTP Verbs to Status Codes
Follow this standard decision matrix when returning HTTP status codes for RESTful API routes:
| HTTP Method | Primary Success Code | Empty Success Code | Validation Error Code | Not Found Code |
|---|---|---|---|---|
| GET | 200 OK | 200 OK (empty array) | 400 Bad Request | 404 Not Found |
| POST | 201 Created | 202 Accepted | 422 Unprocessable Entity | 400 Bad Request |
| PUT | 200 OK | 204 No Content | 422 Unprocessable Entity | 404 Not Found |
| PATCH | 200 OK | 204 No Content | 422 Unprocessable Entity | 404 Not Found |
| DELETE | 204 No Content | 200 OK | 400 Bad Request | 404 Not Found |
8. Test and Validate API Responses with QuizOxa Tools
When building and debugging API endpoints, sanitize and validate your JSON payloads and JWT authorization tokens using QuizOxa free developer tools:
- JSON Validator & Formatter: Validate 400 and 422 JSON response body payloads directly in browser memory.
- JWT Decoder: Inspect 401 Unauthorized token signatures, expiration claims (exp), and user roles safely.
- Diff Checker: Compare 200 OK vs 500 error response structures to trace API payload breaking changes.
9. Frequently Asked Questions (FAQ)
What is the difference between 401 Unauthorized and 403 Forbidden?
401 Unauthorized means the request lacks valid authentication credentials (e.g., missing or expired JWT token). 403 Forbidden means the user is successfully authenticated, but lacks permission (RBAC role) to access the resource.
Should I return 301 or 302 for website domain redirects?
Use 301 Moved Permanently for permanent domain migration or canonical HTTP-to-HTTPS redirects to pass SEO link equity. Use 302 Found only for temporary location changes (such as promotional landing page redirects).
What causes a 502 Bad Gateway error in Nginx?
A 502 Bad Gateway occurs when Nginx acts as a reverse proxy but receives a connection refused or crashed response from the upstream application server (e.g. Node.js, PM2, Python Gunicorn, or PHP-FPM).
When should I use 422 Unprocessable Entity vs 400 Bad Request?
Use 400 Bad Request when the request has malformed syntax (e.g. broken JSON brackets). Use 422 Unprocessable Entity when the JSON syntax is valid, but payload field values fail domain validation rules (e.g. invalid email format or password length).
10. Conclusion & Next Steps
Mastering HTTP status codes improves API design consistency, user experience, and backend observability. Bookmark this HTTP Status Codes Cheat Sheet and leverage QuizOxa Free Developer Tools to validate and debug your API payloads with confidence.