HTTP errors are clues, not diagnoses. This guide gives you a repeatable workflow for interpreting common 4xx and 5xx responses, checking the request and server evidence, choosing safe retry behavior, and recording enough context to resolve API failures without guesswork.
Overview
HTTP status codes describe how a server or intermediary interpreted a request. They do not always identify the precise fault. A 401 may indicate a missing credential, an expired token, or an authentication scheme mismatch. A 404 may mean that a resource does not exist, but it can also result from a wrong base URL, an omitted path parameter, or a route hidden by an authorization layer.
Start by separating the response into two broad classes:
- 4xx responses: the request could not be accepted as sent. Investigate the URL, method, headers, credentials, query parameters, and request body before retrying.
- 5xx responses: the server or an upstream dependency failed while handling an otherwise plausible request. Check server logs, dependency health, timeouts, deployments, and capacity.
The status line is only one part of the evidence. Capture the response headers, response body, request method, sanitized URL, payload shape, timestamp, and correlation or request ID. A structured error body may provide a machine-readable code, field-level validation details, or a support reference that is more useful than the HTTP status alone.
How to compare options
When comparing API debugging approaches, prioritize reproducibility over convenience. A browser, API client, command-line request, automated test, and application log may all show different parts of the same failure. The most useful workflow lets you reproduce the request with a known method, headers, body, and environment.
- Confirm the target. Check the scheme, host, API version, base path, route, query string, and path parameters. Compare the failing request with a known-good request rather than relying on memory.
- Inspect the method. A route may support
GETbut rejectPOST, or requirePATCHrather thanPUT. Look for anAllowheader when the server provides one. - Compare headers. Review authorization,
Content-Type,Accept, idempotency, tenant, locale, and tracing headers. Remove secrets before sharing logs or tickets. - Validate the payload. Confirm valid JSON syntax, required fields, data types, encoding, and whether the endpoint expects a single object, an array, form data, or no body.
- Check timing and environment. Record when the request occurred, whether it happened in local development, CI, staging, or production, and whether a deployment or configuration change preceded it.
- Decide whether retrying is safe. Do not repeatedly retry authentication, validation, permission, or malformed-request errors. For transient server or rate-limit responses, follow the API's guidance and use bounded backoff.
For a practical request-level view, the Chrome DevTools Network Panel Guide covers request headers, cookies, caching, and failed loads. A reproducible command-line request can also remove ambiguity; use the cURL Command Builder Guide to assemble and reuse one safely.
Feature-by-feature breakdown
The table below maps common status codes to the next checks. Treat these as starting points: API-specific documentation and the response body take precedence.
| Status | Likely causes | Request checks | Server checks and retry behavior |
|---|---|---|---|
400 Bad Request | Malformed syntax, invalid query, missing general request data | URL encoding, JSON syntax, parameter names, method | Inspect parser logs and gateway rules. Fix the request; do not blindly retry. |
401 Unauthorized | Missing, expired, malformed, or unsupported credentials | Authorization scheme, token expiry, audience, scope, clock differences | Check authentication configuration and token validation logs. Refresh credentials only when appropriate. |
403 Forbidden | Identity recognized but action or resource is not permitted | User, role, tenant, resource ownership, required scope | Review policy evaluation and access logs. Retrying the same request will not usually help. |
404 Not Found | Wrong route, resource ID, API version, or intentionally hidden resource | Base URL, path spelling, ID format, environment, URL encoding | Check route registration and resource state. Retry only after correcting the target or waiting for expected propagation. |
405 Method Not Allowed | Route exists but does not support the selected method | HTTP method, trailing path, preflight behavior | Inspect route definitions and the Allow response header. Change the method rather than retrying. |
409 Conflict | State conflict, duplicate operation, version mismatch | Idempotency key, current resource version, duplicate identifier | Read current state and apply a conflict-resolution policy. Retrying unchanged data can repeat the conflict. |
415 Unsupported Media Type | Body format is not supported | Content-Type, actual encoding, multipart boundaries | Check parser and content negotiation configuration. Correct the media type before retrying. |
422 Unprocessable Content | Syntax is understood but fields fail validation or business rules | Required fields, formats, ranges, cross-field rules | Use field errors in the response body and application logs. Fix the data; do not use automatic retries. |
429 Too Many Requests | Rate, quota, concurrency, or burst limit exceeded | Request frequency, client sharing, retry schedule | Honor Retry-After when supplied, use exponential backoff with jitter, and cap attempts. |
500 Internal Server Error | Unhandled application exception or unexpected server state | Payload edge cases, correlation ID, request timing | Inspect stack traces, recent releases, and logs. Retry only if the operation is safe and the failure may be transient. |
502 Bad Gateway | Proxy or gateway received an invalid upstream response | Target host, DNS, TLS, proxy route | Check upstream availability and gateway logs. A bounded retry may be reasonable for idempotent requests. |
503 Service Unavailable | Maintenance, overload, unavailable dependency, or deliberate shedding | Retry timing and dependency context | Check health signals and capacity. Back off, respect retry guidance, and avoid synchronized retry storms. |
504 Gateway Timeout | Upstream did not respond within the gateway timeout | Request duration, payload size, client timeout | Trace slow queries and downstream calls. Retry cautiously because the original operation may have completed. |
Authentication failures deserve special care. If you use a JWT, decode it only to inspect non-sensitive claims and never treat decoded client-side content as proof of validity. Compare issuer, audience, expiration, scopes, and signing configuration in server-side logs. For browser-specific failures, also inspect cookies, storage, and cross-origin behavior using the Browser Storage Debugging Guide.
A reusable incident record
Use a compact record that another developer can replay:
Timestamp (UTC):
Environment and service:
Endpoint and HTTP method:
Sanitized query and payload shape:
Status and response body:
Request headers: Content-Type, Accept, auth scheme (redacted), tracing headers
Response headers: Retry-After, Allow, cache, correlation/request ID
Client, build, and deployment version:
Reproduction command or test name:
What changed before the failure:
Server logs, dependency health, and next action:
Keep tokens, passwords, cookies, personal data, and full production payloads out of tickets unless your security process explicitly permits them.
Best fit by scenario
During local integration: begin with a minimal request and add headers and fields one at a time. A JSON formatter or validation utility can expose malformed structure, but it cannot confirm that an API's schema or business rules are satisfied.
In automated tests: assert both the status and the meaningful error contract. Check that validation errors identify fields, authentication failures do not expose sensitive details, and retryable failures do not create duplicate writes. For mocked modules, timers, and API clients, the Vitest Mocking and Spies Guide can help isolate request behavior.
In CI: preserve sanitized response bodies, correlation IDs, timestamps, and the request or test name as artifacts. Separate environment configuration failures from application regressions before rerunning a failing job.
In production: begin with scope: one user, one endpoint, one region, or a broad increase in failures. Compare error rates around deployments and dependency changes, then use traces and logs to follow the request across gateways and services. A 5xx response should become an incident signal, not an instruction to increase retries indefinitely.
When to revisit
Revisit this guide and your team’s runbooks whenever an API version, authentication system, gateway, framework, rate-limit policy, or error response format changes. Also review it after a production incident, a new upstream dependency, a retry-related outage, or a recurring CI failure. Framework defaults and proxy behavior can change the headers, status mapping, and error shape your clients receive.
As a practical maintenance routine, verify once a year that your documented examples still match real responses. Test representative cases for authentication, validation, conflicts, rate limits, and upstream timeouts. Confirm that clients honor Retry-After where appropriate, use bounded backoff, and distinguish safe from non-safe operations. Finally, update the incident template with any new correlation fields or redaction rules.
When the next failure appears, resist the urge to classify it from the status code alone. Capture the complete request context, compare it with a known-good call, check the server-side evidence, and choose a correction or retry based on the failure class. That habit turns HTTP status code troubleshooting into a repeatable engineering process.