When an API request fails, the HTTP status code is a starting point—not a complete diagnosis. This practical reference explains common 2xx, 3xx, 4xx, and 5xx responses, identifies what to check next, clarifies whether the client or server is usually responsible, and provides a repeatable workflow for debugging recurring API failures.
Overview
HTTP status codes describe how a server handled a request. The first digit provides a broad category: 2xx generally indicates success, 3xx indicates redirection or cache-related behavior, 4xx usually points to a problem with the request or its permissions, and 5xx indicates that the server or an upstream dependency could not complete a valid request.
That classification is useful, but it does not assign blame automatically. A 401 response may result from an expired token, a missing authorization header, or a server-side authentication configuration problem. A 404 may mean the resource does not exist, or that a gateway routed the request to the wrong service. Always compare the status code with the method, URL, headers, request body, response body, and server-side logs.
For recurring incidents, record more than the code itself. Capture the timestamp, environment, request identifier, endpoint, deployment version, and whether the same request succeeds from another client. If you are comparing staging and production responses, normalize the JSON before examining field-level differences; the API response comparison workflow can help structure that check.
What to track
Use the following reference as a first pass. “Typical ownership” describes where investigation often begins, not a guarantee about the root cause.
| Code | Meaning | Common causes | Typical ownership and next check |
|---|---|---|---|
| 200 OK | The request completed successfully. | None; the response may still contain an application-level error. | Check the response schema and business fields if the client reports failure. |
| 201 Created | A resource was created. | Successful POST or other creation operation. | Confirm the response body, Location header if provided, and persisted resource. |
| 204 No Content | The request succeeded without a response body. | Successful update or delete. | Ensure the client does not attempt to parse an empty body as JSON. |
| 301, 302, or 307 | The resource or request target is redirected. | HTTP-to-HTTPS redirects, changed routes, or proxy rules. | Inspect the Location header and confirm whether the client follows redirects safely. Preserve the method when required. |
| 400 Bad Request | The server cannot process the request as submitted. | Malformed JSON, invalid parameters, missing required fields, or an unsupported value. | Usually client-side. Recheck Content-Type, encoding, schema, and validation details. |
| 401 Unauthorized | Authentication is missing or not accepted. | Missing, expired, malformed, or incorrectly scoped credentials. | Check the Authorization scheme, token expiry, audience, issuer, and clock differences. A JWT debugging workflow can help inspect claims without treating decoded claims as proof of validity. |
| 403 Forbidden | The server understood the request but refuses to authorize it. | Insufficient role, policy restriction, disabled account, or resource ownership rule. | Usually permissions-related. Compare the authenticated identity, scopes, roles, and resource policy. |
| 404 Not Found | The requested route or resource was not found. | Wrong URL, identifier, API version, region, tenant, or deployment route. | Check the exact URL, method, path parameters, base URL, and gateway routing. Confirm that the resource exists in the selected environment. |
| 405 Method Not Allowed | The route exists but does not support the method used. | GET sent instead of POST, or an endpoint has a restricted method set. | Check the API documentation and the Allow header when present. |
| 409 Conflict | The request conflicts with the current resource state. | Duplicate creation, version conflict, state transition failure, or uniqueness constraint. | Inspect the response details and current resource state. Retrying the same request may not help without a state change. |
| 415 Unsupported Media Type | The server does not support the request representation. | Incorrect or missing Content-Type, such as sending form data where JSON is expected. | Check Content-Type, body encoding, and accepted formats. |
| 422 Unprocessable Content | The request format is understood but its content fails validation. | Invalid field values, business rules, or schema validation errors. | Usually client-side. Record field-level error messages and test the smallest valid payload. |
| 429 Too Many Requests | The client has exceeded a rate or usage limit. | Burst traffic, shared credentials, polling loops, or account limits. | Inspect Retry-After and rate-limit headers when provided. Use bounded exponential backoff and avoid immediate retries. |
| 500 Internal Server Error | The server encountered an unexpected condition. | Unhandled exception, invalid configuration, or application defect. | Usually server-side. Correlate the request ID and timestamp with application logs. |
| 502 Bad Gateway | A gateway received an invalid response from an upstream service. | Upstream crash, protocol mismatch, proxy failure, or incomplete response. | Check gateway and upstream logs, service health, and recent deployments. |
| 503 Service Unavailable | The service cannot handle the request at the moment. | Maintenance, overload, unavailable dependency, or failed health checks. | Check service health and retry only when the operation is safe to repeat. |
| 504 Gateway Timeout | A gateway did not receive a timely upstream response. | Slow database query, overloaded dependency, network delay, or timeout mismatch. | Trace latency across the request path rather than simply increasing the client timeout. |
Headers often explain what the status code alone cannot. Review Location for redirects, Allow for supported methods, Retry-After for retry timing, Content-Type for representation errors, and request or trace identifiers for log correlation. Never paste live access tokens, cookies, or sensitive payloads into an online debugging tool or incident ticket. For token-specific checks, see the JWT debugging guide.
Cadence and checkpoints
API debugging improves when the same evidence is collected consistently. During an active incident, compare a failing request with a known-good request as soon as possible:
- Method and URL: Verify the HTTP method, scheme, host, API version, path, query string, and tenant or region parameters.
- Headers: Compare Authorization, Content-Type, Accept, correlation IDs, idempotency keys, and client-specific headers.
- Body: Validate JSON syntax, required fields, data types, date formats, and payload size. A SQL formatter or structured log viewer can make embedded query or JSON errors easier to inspect.
- Authentication and authorization: Determine whether the credential is present, valid, unexpired, correctly scoped, and associated with the expected environment.
- Rate limits and retries: Record response headers, retry intervals, attempt counts, and whether multiple workers are sharing the same limit.
- Server evidence: Search gateway, application, database, and dependency logs using the timestamp and request ID.
For a monthly or quarterly review, group failures by endpoint, status code, deployment version, client, and environment. Track both frequency and duration. A falling error count can hide a growing impact if the remaining failures affect more important operations. For 429, 502, 503, and 504 responses, review retry behavior separately from first-attempt failures; poorly bounded retries can amplify an outage. The API retry and backoff guide covers this distinction in more detail.
How to interpret changes
Look for transitions rather than isolated codes. A new sequence of 401 responses after a deployment may indicate a changed token audience, header handling, or clock configuration. A rise in 403 responses may follow a permissions change even when authentication still succeeds. A shift from 404 to 502 can suggest that routing was corrected but an upstream service is now failing.
Separate transport-level success from application-level success. A 200 response with an error object, empty dataset, or stale result may be a contract problem rather than a healthy operation. Conversely, a 204 response can be correct even though it has no body. Define the expected status codes and response schema for each operation in tests, then alert on meaningful deviations.
Retry based on operation safety, not merely on the presence of a 5xx code. A read request may be safe to retry under controlled conditions, while a create or payment-like operation may require an idempotency key or a confirmed resource state before another attempt. A 400, 401, 403, 404, 405, 409, or 422 generally requires correcting the request or state first; repeating it unchanged is unlikely to solve the problem.
When to revisit
Revisit this reference during integration work, deployment verification, and incident reviews, then schedule a monthly or quarterly maintenance check for systems with recurring API traffic. Update endpoint-specific notes whenever an API version, authentication method, gateway rule, rate limit, framework, or cloud deployment pattern changes. Standards and provider conventions can evolve, so verify assumptions against the documentation for the API and infrastructure you operate.
Use this incident note template to make the next investigation faster:
Incident time and timezone:
Environment and deployment version:
Endpoint and HTTP method:
Status code and response body:
Request ID or trace ID:
Relevant headers:
Authentication and authorization result:
Payload validation result:
Rate-limit or retry details:
Known-good comparison:
Server and dependency log findings:
Immediate action:
Follow-up owner and review date:
Before closing an incident, reproduce the original failure if it is safe, confirm the corrective change with a focused request, and check for related status-code changes elsewhere in the workflow. Keep sanitized examples in your team documentation. A stable history of 401, 403, 404, 409, 429, and 5xx responses turns a status-code lookup into a useful operational feedback loop for API design, testing, and deployment decisions.