HTTP status codes are useful clues, not complete diagnoses. This guide explains what common 2xx, 3xx, 4xx, and 5xx responses usually indicate, what to check next, and how to track recurring failures across the browser, proxy, API, and application so that troubleshooting becomes faster and more consistent.
Overview
An HTTP status code is a response classification sent by a server or an intermediary such as a reverse proxy, gateway, cache, or load balancer. The first digit provides the broad category:
- 2xx: the request was received and handled successfully.
- 3xx: the client needs to follow a redirect or use cached or conditional information.
- 4xx: the request cannot be completed because of something about the client request, credentials, permissions, or requested resource.
- 5xx: a server or upstream service could not successfully complete an otherwise processable request.
The category is only a starting point. A 404 can mean a genuinely missing resource, an incorrect route, or a proxy configuration problem. A 500 can represent an application exception, a failed dependency, or a generic error response emitted by a gateway. Always pair the status with the request method, URL, response headers, timing, request body, and relevant logs.
For browser-based failures, the Browser DevTools Network Panel Guide can help you inspect the request and response in context. For command-line reproduction, use the examples in the curl API Request Examples guide.
What to track
When an endpoint fails, record enough information to compare one occurrence with another. A small incident log is often more useful than an isolated screenshot of an error page.
Common response codes and first checks
| Code | Typical meaning | What to check next |
|---|---|---|
| 200 OK | The request completed successfully. | Confirm the response body, schema, and business result are correct; a 200 can still contain an application-level error. |
| 201 Created | A resource was created. | Check the returned identifier, representation, and location information if the API provides it. |
| 204 No Content | The request succeeded without a response body. | Make sure the client does not attempt to parse an empty body as JSON. |
| 301 / 308 | A resource has moved permanently. | Inspect the Location header, redirect target, method handling, and cached redirect behavior. |
| 302 / 307 | A temporary redirect is being requested. | Check whether the redirect is expected and whether the client preserves the original method and body. |
| 304 Not Modified | A conditional request can use its cached representation. | Review cache validators such as ETag or Last-Modified and confirm the client has a usable cached response. |
| 400 Bad Request | The server cannot process the request as sent. | Validate JSON syntax, query parameters, required headers, content type, and encoding. |
| 401 Unauthorized | Authentication is missing, invalid, or expired. | Check the Authorization header, token format, issuer, audience, expiration, and clock differences where relevant. |
| 403 Forbidden | The request is understood but not permitted. | Compare the caller's role, scopes, resource ownership, network restrictions, and server authorization rules. |
| 404 Not Found | The requested resource or route was not found. | Verify the hostname, path, API version, route registration, identifier, and proxy forwarding rules. |
| 405 Method Not Allowed | The route exists but does not accept the request method. | Check the method and the Allow header, then compare the client request with the API contract. |
| 408 Request Timeout | The server or intermediary timed out while waiting for the request. | Inspect client uploads, idle timeouts, network conditions, and proxy timeout settings. |
| 409 Conflict | The request conflicts with the current resource state. | Look for duplicate identifiers, version conflicts, or state transitions that are no longer valid. |
| 422 Unprocessable Content | The request format is understood but its data fails validation. | Read field-level errors and compare values with the API's validation rules. |
| 429 Too Many Requests | The caller is being rate limited. | Check retry guidance, request bursts, client concurrency, quotas, and whether retries use backoff. |
| 500 Internal Server Error | The application or server encountered an unexpected failure. | Match the request to application logs, stack traces, recent deployments, and failed dependencies. |
| 502 Bad Gateway | A gateway received an invalid response from an upstream service. | Check upstream health, DNS, TLS, connection errors, response formatting, and gateway logs. |
| 503 Service Unavailable | The service is temporarily unable to handle the request. | Inspect capacity, maintenance state, health checks, deployment status, and dependency availability. |
| 504 Gateway Timeout | A gateway did not receive an upstream response in time. | Trace latency through each hop and compare application, database, proxy, and client timeout limits. |
Track the timestamp with a timezone, request method, route template, status code, response time, request ID or trace ID, deployment version, and upstream service. Avoid storing access tokens, passwords, or unnecessary personal data in diagnostic notes. If the response contains JSON, validate and inspect it with a trusted JSON formatter and validator rather than copying sensitive payloads into an unapproved tool.
Cadence and checkpoints
HTTP troubleshooting is most effective when request behavior is reviewed at several timescales rather than only during an outage.
During an incident
- Reproduce the failure with the smallest safe request. Record whether it occurs in the browser, a command-line client, or both.
- Capture the complete URL, method, relevant headers, status, response headers, and timing breakdown.
- Follow the request path: client, DNS, CDN or cache, load balancer, reverse proxy, API gateway, application, database, and external dependencies.
- Use the request ID or trace ID to find matching entries in each layer's logs.
- Compare a failing request with a successful request for the same route, especially authentication, content type, payload shape, and routing headers.
After a deployment or configuration change
Check status-code counts and latency by endpoint before and after the change. A new 404 pattern may indicate a route or base-URL mismatch. A rise in 401 or 403 responses may point to changed credentials, scopes, cookie settings, or environment variables. A rise in 502 or 504 responses usually calls for a hop-by-hop review rather than a client-only fix.
Monthly or quarterly review
Review recurring errors on a monthly or quarterly cadence, depending on traffic and operational risk. Group results by route, status, caller, deployment version, and upstream dependency. Look for endpoints that repeatedly return errors even when the overall rate appears small. Also review redirect chains, timeout settings, rate-limit behavior, and the quality of error bodies provided to API consumers.
How to interpret changes
Changes in status-code volume are signals that need context. A larger count may simply reflect higher traffic, while a stable count can hide a worse failure rate if successful requests increased.
- More 4xx responses from one client: compare its release version, request schema, authentication flow, and base URL with a known-good client.
- More 401 responses across clients: inspect token issuance, expiration, signing configuration, clock handling, and authorization-header forwarding.
- More 403 responses for selected resources: review permission changes, tenant boundaries, role mappings, and resource ownership checks.
- More 404 responses after routing changes: verify API version prefixes, trailing-slash behavior, proxy rewrites, and route registration.
- More 429 responses: identify whether retries, parallel jobs, scheduled tasks, or a newly released client are creating bursts. A cron expression guide can help when scheduled jobs unexpectedly overlap.
- More 5xx responses after a release: correlate errors with the deployment, configuration, database migrations, dependency changes, and resource limits.
- More 504 responses without more 500 responses: inspect latency and timeout boundaries between services. The application may still be working, but a gateway may stop waiting before the response arrives.
Do not treat a status code as proof of a single root cause. Confirm the interpretation with logs, traces, and a controlled reproduction. For example, a gateway-generated 502 may never appear in the application log, while an application-generated 500 may include a trace ID that the gateway does not expose unless configured to do so.
When to revisit
Revisit this guide whenever a deployment produces a new error, an API integration changes, a redirect chain is modified, or an incident reveals a gap in request tracing. Schedule a broader review monthly or quarterly to keep the status-code table, framework examples, reverse-proxy assumptions, and cloud-platform notes aligned with the systems you actually operate.
Use this practical checklist at the next failure:
- Identify the exact status, method, route, timestamp, and request ID.
- Determine which layer generated the response.
- Compare the failing request with a successful request.
- Check authentication, authorization, routing, payload validation, rate limits, and timeout boundaries in that order when appropriate.
- Correlate the request across proxy, application, database, and dependency logs.
- Record the confirmed cause, the corrective change, and a regression check.
Keep the resulting notes with your API runbook and update them after meaningful infrastructure or application changes. A consistent record of status codes, request context, and corrective actions turns recurring HTTP errors into trackable engineering work instead of repeated guesswork.