When an API request fails, the HTTP status code is only the starting point. This practical workflow explains what common codes mean, what to inspect in headers, response bodies, and logs, how to handle authentication and rate limits, and which troubleshooting signals to track over time.
Overview
HTTP status codes provide a shared vocabulary between clients, servers, proxies, gateways, and monitoring systems. A 4xx response usually indicates that the request cannot be completed as sent, while a 5xx response generally indicates a problem while processing a valid request. That distinction is useful, but it is not sufficient for diagnosis: a gateway may generate a response before the application receives the request, and an application may return a custom error body with details that the status code does not reveal.
Start by recording the complete request and response context, not just the number shown in a browser or SDK exception. Capture the HTTP method, URL path, query parameters, relevant request headers, response headers, response body, elapsed time, and any request or correlation ID. Remove credentials, cookies, personal data, and other secrets before sharing logs or a HAR file. The HAR file safety guide provides a useful checklist for preparing browser network captures.
For request and response structure, compare the failing exchange with the API contract. An OpenAPI validation workflow can help identify incorrect parameters, missing fields, incompatible content types, or a response that no longer matches the documented schema. If the payload itself is difficult to inspect, use a JSON formatter and validator to make syntax and nesting errors visible.
Quick reference: common HTTP status codes
| Status | Typical meaning and likely causes | Cache or authentication implications | Retry safety | Recommended client behavior |
|---|---|---|---|---|
| 400 Bad Request | The server cannot process the request as sent. Check malformed JSON, invalid parameters, missing required fields, or an unsupported value. | Do not assume authentication is the issue. Caching is normally not the primary concern. | Not automatically safe. Correct the request first. | Read the error body, validate the payload, and return a useful correction message. |
| 401 Unauthorized | Credentials are missing, expired, malformed, or not accepted by the endpoint. | Inspect authentication headers and token expiry. A 401 does not prove that the user lacks permission. | Only retry after refreshing or correcting credentials, and avoid repeated attempts with the same invalid token. | Authenticate or refresh the credential, then retry once when appropriate. See the JWT debugging guide for safe claim inspection. |
| 403 Forbidden | The server understood the request but will not authorize the requested action. The account, role, scope, network, or resource policy may be involved. | Changing or refreshing a token may not help if the identity still lacks the required permission. | Usually not useful to retry unchanged. | Check scopes, roles, ownership, tenant context, and endpoint permissions. |
| 404 Not Found | The route or resource was not found. The path, API version, identifier, environment, or resource visibility may be wrong. | Check whether an intermediary or application intentionally hides unauthorized resources as 404. Do not infer the exact cause without logs or documentation. | Not useful unless the resource may appear after an asynchronous operation. | Verify the URL, deployment, identifier, and resource lifecycle. |
| 405 Method Not Allowed | The path exists, but the HTTP method is not supported for it. | Inspect the Allow response header when supplied. Authentication is usually secondary. | Retry with the documented method, not the same method. | Check route definitions and client method configuration. |
| 409 Conflict | The request conflicts with the current resource state, such as a duplicate creation or a version/concurrency conflict. | Usually an application-state issue rather than a cache issue. | Only retry after resolving the conflict or re-reading current state. | Use the response details to decide whether to update, rename, refresh, or abandon the operation. |
| 422 Unprocessable Content | The request is syntactically valid but fails validation or business rules. | Authentication may be valid; inspect field-level errors. | Not safe to repeat unchanged. | Present validation details and correct the submitted values. |
| 429 Too Many Requests | The client has exceeded a rate or concurrency limit, or a gateway has applied throttling. | Inspect Retry-After and any documented rate-limit headers. Caching a failed response does not remove the limit. | Retry only with delay, preferably using bounded exponential backoff and jitter. | Reduce request volume, honor the server's timing guidance, and prevent many workers from retrying together. |
| 500 Internal Server Error | The server encountered an unexpected condition while processing the request. | Do not expose internal details to end users. Check server logs and correlation IDs. | Depends on the method and operation. A repeat may duplicate a non-idempotent action. | Capture evidence, check whether the operation completed, and retry cautiously. |
| 502 Bad Gateway | A proxy or gateway received an invalid response from an upstream service. | Inspect gateway headers, upstream timing, and service health. Browser results may reflect an intermediary rather than the application. | Often retryable for safe or idempotent operations, subject to limits. | Check upstream availability, DNS, TLS, timeouts, and gateway logs. |
| 503 Service Unavailable | The service is temporarily unable to handle the request, possibly because of maintenance, overload, or dependency failure. | Honor Retry-After when present. Avoid turning an outage into a retry storm. | Potentially retryable with bounded backoff. | Use health signals and queueing; distinguish temporary unavailability from a persistent deployment problem. |
| 504 Gateway Timeout | A gateway did not receive a timely response from an upstream service. | The upstream operation may still have completed even though the client saw a timeout. | Retry carefully, especially for create, charge, delete, or other non-idempotent operations. | Check operation status or use an idempotency key before repeating the request. |
Status meanings can be refined by the API's documentation and error contract. A framework, reverse proxy, cloud gateway, or application may add fields such as code, type, detail, errors, or request_id. Treat those fields as diagnostic evidence, not as a replacement for the HTTP status.
What to track
A small, consistent evidence set makes recurring API failures easier to compare. For every representative failure, track:
- Request identity: timestamp, environment, service, endpoint, HTTP method, API version, and a redacted correlation or request ID.
- Request shape: content type, payload size, query parameters, required headers, authentication scheme, and whether the request was generated by a browser, SDK, job, or command-line client.
- Response details: status code, response body fields, content type,
Retry-After, cache headers, gateway headers, and elapsed time. - Resource state: whether the operation changed data despite returning an error, whether a duplicate now exists, and whether a later status check confirms completion.
- Frequency and distribution: counts by endpoint, status, client version, region or environment, dependency, and release.
- Recovery behavior: whether the client retried, how long it waited, whether backoff was applied, and whether the eventual result was successful.
Authentication failures deserve a separate comparison. For a 401, verify that the expected credential was sent, the token is intended for the correct audience or service, its expiration is valid, and the server accepts the signing or authentication method. For a 403, compare the authenticated identity's roles and scopes with the permission required by the endpoint. Never paste live tokens into public online tools, issue trackers, or shared screenshots.
For 429, 502, 503, and 504 responses, record timing and concurrency. A failure that appears only during bursts points toward capacity, rate limits, connection pools, or queue behavior. A failure that begins after a deployment may indicate a configuration, routing, schema, or dependency change. Keep payload validation separate from transport diagnosis: use the JSON validation and formatting guide for malformed payloads, and use logs and traces for server-side behavior.
Cadence and checkpoints
Use the following checkpoints during an incident and as part of routine developer workflow:
- First five minutes: Reproduce the request with a known-safe test account or fixture. Capture the exact status, body, headers, timestamp, and correlation ID. Confirm whether the failure affects one endpoint or several.
- After reproduction: Compare a successful and failing request side by side. Check method, URL encoding, headers, body schema, token context, and environment. A URL encoder or JSON formatter can help reveal invisible differences, but do not submit confidential values to an untrusted service.
- During investigation: Follow the request through client logs, gateway access logs, application logs, and dependency traces. Search by correlation ID and align timestamps, allowing for clock differences between systems.
- Before retrying: Classify the operation as safe to repeat, conditionally safe, or non-idempotent. Add an idempotency key where the API supports it, or check resource state before repeating a timed-out write.
- After resolution: Record the root cause, the observable signal that identified it, the safe client behavior, and a regression test or alert that would detect recurrence.
For operational review, a monthly or quarterly check is usually enough for stable integrations. Review status-code volume, retry rates, latency around failures, authentication rejection patterns, and rate-limit responses. Compare the period with the previous review rather than relying only on a single total. A low overall error count can still hide a severe problem concentrated in one customer, endpoint, deployment, or region.
Keep a short compatibility log for dependencies and platform boundaries. Note API version changes, proxy or gateway configuration changes, authentication policy changes, SDK upgrades, timeout changes, and new response-body formats. This is especially useful when an integration spans several teams that release on different schedules.
How to interpret changes
Look for patterns before choosing a fix. A rise in 400 or 422 responses after a client release often suggests a payload, encoding, validation, or contract mismatch. A rise in 401 responses can indicate expired credentials, a missing header, clock skew, or an incorrect environment. A rise in 403 responses is more consistent with permissions, scopes, resource ownership, or policy changes. These are starting hypotheses, not conclusions.
Separate client-visible status from the layer that generated it. If a gateway returns 502 or 504, the application may have no corresponding application log because the request failed before reaching it or because the gateway timed out first. Conversely, a 500 with a stable application correlation ID usually warrants application and dependency investigation. Compare gateway timing, upstream timing, and application timing when those measurements are available.
Retry metrics require similar care. A higher success rate after retries may show that transient failures are being recovered, but it may also conceal increased load or duplicate side effects. Track both the first-attempt result and the final result. For 429 and 503 responses, verify that backoff is bounded and distributed across workers. For a timeout on a write, confirm the resource state before retrying; the absence of a response is not proof that the server did nothing.
Cache behavior can complicate diagnosis. Inspect Age, Cache-Control, ETag, and related headers where relevant, and check whether a proxy is serving a stale or transformed response. Do not cache error responses broadly without understanding the API's cache rules, because a temporary failure or authorization result may be replayed to later requests.
When to revisit
Revisit this troubleshooting record at least monthly or quarterly for active integrations, and immediately after any change that can affect request handling. The most useful triggers include an API version migration, authentication or permission change, gateway or proxy modification, SDK upgrade, deployment, new rate-limit behavior, altered timeout settings, or a change to error-body fields.
Make the review action-oriented. Export the latest status-code counts, identify the largest change from the previous period, select one recurring failure, and reproduce it with a controlled request. Confirm that the documented client response still matches the API's current behavior. Then update tests, dashboards, runbooks, and retry settings where necessary.
Before closing an incident or integration task, answer these questions:
- What exact request produced the error, and can it be reproduced safely?
- Which layer generated the response: client, gateway, application, or dependency?
- Does the response body contain a stable machine-readable error code?
- Was authentication valid, and were permissions sufficient?
- Is retrying safe for this method and operation?
- Did the operation change server state despite the error?
- What log, metric, test, or alert will make the next occurrence faster to diagnose?
Keep this checklist beside your API client tests and incident notes. When a request fails again, begin with the status table, collect the same evidence, and compare it with the previous checkpoint. Consistent observation turns HTTP errors from isolated surprises into recognizable patterns that developers can correct without guesswork.