Tool Lockers guide
HTTP Status Codes Cheat Sheet: Common 2xx–5xx Codes
A concise guide to common HTTP response codes, what they signal, and how to troubleshoot API responses.
By Tool Lockers
Read the status class first
An HTTP status code is a three-digit response code. The first digit gives a quick category:
- 2xx: the request succeeded.
- 3xx: the client may need to follow a redirect or use a cached response.
- 4xx: the request or caller cannot be fulfilled as sent.
- 5xx: the server or an upstream dependency failed while handling a valid-looking request.
The exact behavior still depends on the method, response headers, API contract, and application.
Common codes
| Code | Short meaning | Typical check |
|---|---|---|
| 200 | OK | Inspect the response body and confirm it matches the API contract. |
| 201 | Created | Check the created resource location or returned identifier. |
| 204 | No Content | A successful response has no body; do not try to parse JSON blindly. |
| 301 / 308 | Permanent redirect | Check the Location target and whether the method should be preserved. |
| 302 / 307 | Temporary redirect | Check the target; 307 preserves the request method. |
| 304 | Not Modified | A conditional request can reuse a cached representation. |
| 400 | Bad Request | Validate syntax, query parameters, and required fields. |
| 401 | Unauthorized | Check authentication credentials and token expiry. |
| 403 | Forbidden | Authentication may be present, but permission is insufficient. |
| 404 | Not Found | Check the path, resource identifier, and deployment environment. |
| 409 | Conflict | Resolve a state conflict, duplicate, or version mismatch. |
| 422 | Unprocessable Content | The syntax may be valid while the submitted values violate validation rules. |
| 429 | Too Many Requests | Respect any Retry-After header and apply backoff. |
| 500 | Internal Server Error | Check server logs and correlation IDs; avoid exposing internal details. |
| 502 / 503 / 504 | Gateway or service unavailable | Check upstream health, timeouts, and retry policy. |
These are common interpretations, not a guarantee of how every service uses a code. Read the API documentation and response body.
Debug an API response
Start with the exact request URL, method, and authentication context. Then inspect the status, response headers, and body. A 401 and 403 usually point to different problems: one concerns valid authentication, while the other concerns authorization or policy. A 429 should not be retried in a tight loop; use a bounded backoff and follow server guidance.
For a 5xx response, capture a request ID if provided and check server-side logs. Repeating a non-idempotent request can create duplicate work, so understand the operation and retry rules before sending it again.
Look up a code with the HTTP Status Lookup, or send a test request and inspect the result with the API Tester. A status code alone rarely explains the complete failure; combine it with headers, the response body, and service logs.