HTTP status codes are clues, not complete diagnoses. This reference explains what common API response codes usually mean, what to check next, and how to build a repeatable debugging workflow for authentication, payload, redirect, rate-limit, and server failures.
Overview
An API response normally contains three useful parts: the HTTP status code, response headers, and the response body. Read them together. A 401 may indicate an expired token, but the WWW-Authenticate header or a provider-specific error body may tell you whether the token is missing, malformed, or rejected for another reason. Similarly, a 400 does not automatically mean the server is broken; it often means the request did not match the API contract.
The first digit groups responses by outcome:
- 2xx: the request was processed successfully.
- 3xx: the client may need to follow a redirect or use cached data.
- 4xx: the request cannot be fulfilled as sent, or the client lacks permission.
- 5xx: the server or an upstream dependency failed to complete a valid request.
For a fast first pass, record the method, full URL, status code, response headers, sanitized request body, response body, and request ID if one is provided. Reproducing the same request with a command-line client or an API debugging tool can help separate application behavior from browser behavior.
What to track
Use the following reference as a starting point. The exact meaning of an error body, authentication scheme, or validation response depends on the API contract, so check the endpoint documentation when available. You can use your browser’s find function to search this table for a code.
2xx: successful responses
| Code | Typical meaning | What to check |
|---|---|---|
200 OK | The request succeeded and a response body may be present. | Confirm the returned data matches the requested resource and filters. |
201 Created | A new resource was created. | Look for the created resource, often in the response body or Location header. |
202 Accepted | The request was accepted for processing, but work may not be complete. | Check for a job identifier, polling URL, or documented completion mechanism. |
204 No Content | The request succeeded without a response body. | Do not parse the body as JSON; verify the client handles an empty response. |
3xx: redirects and caching
| Code | Typical meaning | What to check |
|---|---|---|
301 or 308 | The resource has moved permanently. | Update the configured endpoint when appropriate and inspect whether the HTTP method is preserved. |
302 or 307 | The server is redirecting the request temporarily. | Inspect the Location header and confirm the client follows redirects safely. |
304 Not Modified | The cached representation can be reused. | Check conditional headers such as If-None-Match or If-Modified-Since. |
Redirects deserve special attention in APIs. A client may not send the original authorization header to a different host, and redirect handling can vary between libraries. Treat unexpected redirects as a configuration issue rather than silently following them during diagnosis.
4xx: request, authentication, and client errors
| Code | Typical meaning | What to check next |
|---|---|---|
400 Bad Request | The server cannot process the request as formatted. | Check JSON syntax, query parameters, required headers, data types, and malformed URLs. |
401 Unauthorized | Authentication is missing, invalid, or no longer accepted. | Check the authorization scheme, token format, expiry, audience, issuer, and environment. |
403 Forbidden | The server understood the request but will not authorize it. | Compare scopes, roles, resource ownership, organization access, and endpoint permissions. |
404 Not Found | The resource or route was not found, or its existence is intentionally hidden. | Check the base URL, API version, identifier, deployment environment, and HTTP method. |
405 Method Not Allowed | The route exists but does not accept that method. | Inspect the endpoint documentation and the Allow header when provided. |
409 Conflict | The request conflicts with the current resource state. | Look for duplicate identifiers, stale versions, or state-transition rules. |
422 Unprocessable Content | The request is understood but fails validation or semantic rules. | Map field-level errors to the submitted payload and preserve the server’s error details. |
429 Too Many Requests | The client has exceeded a rate or concurrency limit. | Read rate-limit headers, honor Retry-After when present, and reduce request bursts. |
5xx: server and upstream failures
| Code | Typical meaning | What to check next |
|---|---|---|
500 Internal Server Error | The server encountered an unexpected condition. | Check server logs, correlation IDs, recent deployments, and the smallest reproducible request. |
502 Bad Gateway | A gateway or proxy received an invalid response from an upstream service. | Inspect upstream health, proxy configuration, timeouts, and dependency responses. |
503 Service Unavailable | The service is temporarily unable to handle the request. | Check maintenance state, capacity, dependency health, and retry guidance. |
504 Gateway Timeout | A gateway did not receive a timely upstream response. | Compare client, proxy, and server timeouts; investigate slow queries or downstream calls. |
Cadence and checkpoints
Debug the request in a consistent order so that each test removes one possible cause. Start by confirming the endpoint, environment, DNS name, HTTP method, and API version. A request sent to staging with production credentials, or to a collection URL instead of an item URL, can produce misleading results.
- Reproduce the response. Capture the exact request and determine whether the failure is consistent or intermittent.
- Validate the method and URL. Check spelling, path parameters, trailing slashes, query encoding, and redirects.
- Inspect authentication. Confirm that the expected header is present, the token belongs to the intended environment, and its claims or expiry are suitable. A browser-based JWT decoder online can help inspect non-secret token claims, but never paste sensitive tokens into an untrusted tool.
- Validate headers and payload. Compare
Content-Type,Accept, required custom headers, JSON structure, and field types. A JSON formatter online can make a nested response or request easier to inspect. - Check limits and retries. Identify whether the failure follows a burst, a long-running request, or a repeated retry loop. Retry only failures that are safe to repeat, preferably with bounded exponential backoff and jitter.
- Move to server evidence. For 5xx responses, correlate the request timestamp and request ID with gateway, application, database, and dependency logs.
Keep a small incident record containing the first failing request, the last known successful request, code and version changes, and whether the issue affects one resource or the whole endpoint. This makes recurring failures easier to compare during monthly or quarterly reviews.
How to interpret changes
A status-code change is useful only when you compare it with the request and response details around it. A shift from 401 to 403 may indicate that authentication now works but authorization is still missing. A shift from 400 to 422 may mean the JSON is now syntactically valid and has reached field-level validation. These are not universal rules, but they are useful diagnostic signals.
Look for patterns across time and dimensions:
- Endpoint: one route may have a schema or deployment issue while others remain healthy.
- Caller and credential: failures limited to one role, tenant, or token usually point toward authorization or configuration.
- Payload size and shape: large bodies, optional fields, and boundary values can expose validation or timeout problems.
- Time and volume: spikes in
429,502, or504responses can align with traffic, scheduled jobs, or dependency load. - Deployment version: correlate a new error pattern with releases, infrastructure changes, schema migrations, or proxy updates.
Do not treat every 4xx response as a bug in the client or every 5xx response as proof that the API is down. Provider-specific conventions, gateways, validation layers, and security controls can affect the code returned. The response body, headers, logs, and API contract provide the necessary context.
When to revisit
Use this reference whenever an API request fails, but review your team’s status-code handling on a regular cadence as well. A monthly check is useful for active integrations; a quarterly check may be sufficient for stable internal tools. Revisit sooner after an API version change, authentication change, gateway migration, rate-limit adjustment, new dependency, or incident involving retries.
During each review, sample successful and failed requests, confirm that clients handle empty 204 responses and asynchronous 202 responses correctly, verify that authentication errors do not trigger unsafe retry loops, and check that logs do not expose tokens or sensitive payloads. Update runbooks when a provider changes its error body, headers, retry guidance, or validation behavior.
For the next failure, follow this short checklist:
- Save the status code, headers, response body, timestamp, and request ID.
- Confirm the method, URL, environment, authorization, and content type.
- Validate the payload and compare it with a known-good request.
- Check redirects, rate limits, timeout settings, and retry behavior.
- Use server and dependency logs for 5xx responses.
- Record the cause and update the client test or runbook so the same issue is faster to diagnose next time.
For recurring scheduled requests, pair this review with a cron expression builder check so timing, retries, and overlapping jobs are considered together. Consistent evidence collection turns a status code from a vague alert into a practical next action.
