HTTP status codes are useful signals, but they rarely identify the complete cause of an API failure on their own. This practical guide explains what common 1xx–5xx responses mean, which headers and request details to inspect, how to verify behavior with curl, when retries are safe, and how to build a repeatable troubleshooting workflow for integrations, tests, monitoring alerts, and production incidents.
Overview
An HTTP status code describes how a server handled a request at the protocol level. It does not always explain why an application rejected the request, and a successful status does not guarantee that the response body matches the API contract. Treat the code as the first branch in an investigation:
- 1xx informational: the request process is continuing.
- 2xx success: the server accepted or completed the request.
- 3xx redirection: the client may need to follow a different location or use a cached representation.
- 4xx client error: the request, credentials, permissions, or client state need attention.
- 5xx server error: the server or an upstream dependency could not complete a seemingly valid request.
Frameworks and API gateways can add their own details, so always inspect the response body, headers, request method, URL, and correlation or request ID alongside the status code. A useful debugging record contains the exact timestamp, environment, sanitized request, response status, relevant headers, and a short description of the expected result.
What to track
HTTP status code reference
The table below is a compact troubleshooting matrix. “Retry” describes a reasonable default, not an unconditional rule. Confirm the operation’s safety and the API’s documented behavior before repeating a request that changes data.
| Code | Meaning | Likely cause and checks | Retry guidance |
|---|---|---|---|
| 100 | Continue | The server received request headers and is waiting for the request body. Check client streaming and Expect behavior. | Continue the same request if the client supports it. |
| 101 | Switching Protocols | The server agreed to change protocols, commonly for an upgrade. Inspect upgrade and connection headers. | Do not repeat as a normal REST request; complete the protocol negotiation. |
| 102 | Processing | The server is still working on a request. Long-running or WebDAV-style operations may use it. | Wait according to the client timeout and API guidance. |
| 103 | Early Hints | Preliminary headers may arrive before the final response. Confirm the client handles informational responses correctly. | Wait for the final status code. |
| 200 | OK | The request succeeded. Validate the response schema, content type, pagination, and business result rather than stopping at the code. | No retry is normally needed. |
| 201 | Created | A resource was created. Inspect the Location header and response body for its identifier. | Do not retry blindly; a second attempt could create a duplicate. |
| 202 | Accepted | The server accepted work for asynchronous processing. Look for an operation ID or polling location. | Poll the documented endpoint, not the original mutation. |
| 204 | No Content | The request succeeded without a response body. A client that always parses JSON may report a secondary error. | No retry is normally needed. |
| 301, 302, 307, 308 | Redirection | Inspect Location. 307 and 308 preserve the method more explicitly than common legacy redirect handling. | Follow only trusted locations and verify how the client preserves method and credentials. |
| 304 | Not Modified | A conditional request can use its cached representation. Check ETag, If-None-Match, and cache behavior. | Use the valid cached response. |
| 400 | Bad Request | Malformed JSON, invalid parameters, an unsupported value, or a failed server-side request parser is likely. Inspect the body and content type. | Fix the request before retrying. |
| 401 | Unauthorized | Authentication is missing, expired, malformed, or not accepted. Check the authorization scheme, token audience, expiry, and server time. | Refresh credentials when appropriate; do not repeatedly retry invalid credentials. |
| 403 | Forbidden | The identity is understood but lacks permission, or a policy, network rule, or tenant boundary blocks access. | Retry only after a permission or policy change. |
| 404 | Not Found | Check the URL, API version, resource ID, tenant, region, route, and whether the resource is intentionally hidden. | Fix the target; do not assume a transient failure. |
| 405 | Method Not Allowed | The route exists but does not accept the method. Inspect the Allow header and API documentation. | Use the supported method. |
| 408 | Request Timeout | The server did not receive the request in time, or an intermediary timed out. Compare client, proxy, and server timeout values. | Retry idempotent requests with bounded backoff. |
| 409 | Conflict | State, version, uniqueness, or concurrent update rules prevented the operation. Inspect conflict details and version fields. | Re-read state and resolve the conflict before retrying. |
| 412 | Precondition Failed | An If-Match, If-None-Match, or similar condition was false. | Refresh the representation and recalculate the precondition. |
| 413 | Content Too Large | The request body exceeds a server or intermediary limit. Check payload size and upload constraints. | Reduce or split the payload if supported. |
| 415 | Unsupported Media Type | The Content-Type is absent or unsupported, such as sending form data where JSON is expected. | Correct the media type and body format. |
| 422 | Unprocessable Content | The syntax is understood, but validation or business rules reject the content. Read field-level errors. | Correct invalid fields; do not retry unchanged input. |
| 429 | Too Many Requests | Rate or concurrency limits were exceeded. Inspect Retry-After and any documented quota headers. | Back off, add jitter, and respect the server’s guidance. |
| 451 | Unavailable for Legal Reasons | The resource is unavailable because of a legal or policy restriction communicated by the service. | Escalate through the service’s documented channel rather than looping. |
| 500 | Internal Server Error | An unhandled application error or server configuration problem occurred. Use a request ID and server logs to correlate. | Retry only when the operation is safe and transient behavior is plausible. |
| 501 | Not Implemented | The server does not support the requested capability or method. | Change the request or server capability; retries will not help. |
| 502 | Bad Gateway | A gateway received an invalid response from an upstream service. Check dependency health, DNS, TLS, and proxy logs. | Bounded retries may help for idempotent requests. |
| 503 | Service Unavailable | The service is overloaded, under maintenance, or unable to serve the request. Look for Retry-After and health signals. | Use exponential backoff and a circuit breaker where appropriate. |
| 504 | Gateway Timeout | An intermediary waited too long for an upstream response. Compare gateway and application latency and trace the dependency chain. | Retry cautiously; the original operation may still be running. |
Headers and request details to record
For authentication failures, capture the authorization scheme without recording the token itself. For throttling, record Retry-After, quota headers, and the request rate. For redirects, inspect Location. For caching, compare ETag, Last-Modified, Cache-Control, and conditional request headers. For failures crossing gateways, look for a request ID, trace ID, server banner, and timing information, while treating infrastructure headers as diagnostic clues rather than proof of the root cause.
Use curl to separate client and server behavior
Start with headers and a response body:
curl --verbose --request GET \
--header 'Accept: application/json' \
'https://api.example.test/v1/items?id=123'
To inspect a JSON request, make the method, content type, and body explicit:
curl --verbose --request POST \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer REDACTED' \
--data '{"name":"example"}' \
'https://api.example.test/v1/items'
Use a harmless endpoint or a read-only request when testing. Redact tokens, cookies, personal data, and sensitive payloads before sharing command output. If a browser request fails but curl succeeds, compare origin, CORS behavior, cookies, preflight requests, redirects, and browser-specific headers.
Cadence and checkpoints
HTTP debugging is easier when status-code behavior is tracked rather than investigated only during an incident. Add these checkpoints to a monthly or quarterly engineering review:
- Review status distributions: separate 4xx failures caused by callers from 5xx failures caused by services. Track rates by endpoint, method, environment, and dependency.
- Review latency with errors: a rising 504 rate or a growing number of slow 200 responses may point to the same dependency or timeout problem.
- Review retry volume: confirm clients retry only transient responses, use bounded exponential backoff, and avoid retrying non-idempotent operations without an idempotency design.
- Review response contracts: verify that error bodies remain machine-readable, content types are correct, and clients can handle empty 204 responses and asynchronous 202 responses.
- Reproduce representative failures: keep sanitized
curlcommands or automated tests for recurring 400, 401, 403, 404, 409, 429, and 5xx cases.
After a release, infrastructure change, authentication change, or API version migration, run the review sooner. Changes to gateways, proxy limits, TLS termination, routing, schemas, and rate limits can alter status-code patterns without changing application code.
How to interpret changes
A single status code is rarely enough to identify a trend. Compare the current pattern with a known-good period and segment the data before assigning ownership.
- More 400 or 422 responses: check client releases, schema changes, serialization, validation rules, and documentation examples.
- More 401 responses: check token expiry, clock skew, secret rotation, audience or issuer configuration, and whether credentials are being sent to the intended host.
- More 403 responses: compare role, tenant, network, and policy changes. A 403 is usually not fixed by refreshing a token.
- More 404 responses: check deployments, base URLs, route versions, identifiers, and regional or tenant routing.
- More 409 responses: investigate concurrent writes, stale versions, duplicate keys, and whether clients need an explicit read-modify-write flow.
- More 429 responses: compare traffic bursts, concurrency, client retry amplification, and quota changes. A retry storm can make the original problem worse.
- More 502, 503, or 504 responses: trace the request across gateway, application, database, and external dependencies. Compare timeout settings and saturation signals.
Also check for misleading success. A response may be 200 while containing an application-level error, an empty result caused by the wrong tenant, or a schema that a client cannot parse. Validate status, content type, required fields, error shape, and business assertions together. For API contracts, pair this workflow with an OpenAPI validation workflow. For large JSON responses, jq can help filter and compare fields without manually scanning logs.
When to revisit
Revisit this guide during a monthly or quarterly API health review, and immediately after any event that can change request or response behavior. In particular, update your team’s status-code notes when an API introduces a version, changes authentication, adds rate limits, modifies validation, changes gateway timeouts, or adopts a new framework. Framework-specific defaults and gateway mappings can differ, so record the behavior that your service actually exposes.
Use the following action checklist during the next investigation:
- Capture the exact method, URL, timestamp, environment, status code, response body, and relevant headers.
- Remove secrets and personal data, then reproduce the request with
curl --verboseor an equivalent client. - Classify the response as authentication, authorization, routing, validation, conflict, throttling, dependency, or timeout related.
- Check the API’s documented retry and idempotency rules before repeating a mutation.
- Correlate request IDs with gateway, application, and dependency logs.
- Turn the confirmed cause into a regression test, alert, runbook step, or contract check.
- Record the change in your next status-code review so recurring failures become easier to recognize.
For adjacent debugging work, use a compact browser developer toolkit to inspect JSON, JWT claims, regular expressions, and encoded values. Keep secrets out of browser-based utilities; the safe-use guide for online developer utilities provides a useful review point before sharing live API data.