HTTP status codes are short signals about what happened when a client requested a resource. This practical reference explains common 3xx, 4xx, and 5xx responses, shows how to debug API errors with browser tools and curl, and provides a repeatable checklist for routing, authentication, caching, timeouts, and upstream failures.
Overview
An HTTP response contains more than a status code. The code is interpreted alongside the request method, URL, headers, response body, server logs, and application behavior. A 2xx response generally indicates success, a 3xx response involves redirection or cache validation, a 4xx response usually points to the request or client context, and a 5xx response usually indicates that the server could not complete an otherwise understandable request.
These categories are useful starting points, not absolute diagnoses. For example, a missing permission may appear as 401 or 403, while a gateway can return a 502 because an upstream application is unavailable, incorrectly configured, or returning an invalid response. Diagnose the complete request path instead of treating the number as the root cause.
| Class | Meaning | Typical investigation |
|---|---|---|
| 3xx | Redirection or conditional response | Inspect the Location header, redirect chain, cache headers, and canonical URL. |
| 4xx | Request or client-context problem | Check the method, URL, parameters, payload, credentials, permissions, and rate limits. |
| 5xx | Server-side processing failure | Check application logs, dependencies, routing, resource limits, timeouts, and recent deployments. |
Common HTTP response codes
| Code | What it usually means | First checks |
|---|---|---|
| 301, 302, 307, 308 | The resource is redirected. | Review Location, redirect count, HTTP-to-HTTPS rules, and method preservation. |
| 304 | The cached representation is still valid. | Inspect ETag, Last-Modified, and conditional request headers. |
| 400 | The server cannot process the request syntax or input. | Validate JSON, query parameters, encoding, and required fields. |
| 401 | Authentication is required or was not accepted. | Check credentials, token format, expiry, issuer, and the Authorization header. |
| 403 | The server understood the request but refuses it. | Check permissions, policy rules, scopes, IP restrictions, and resource ownership. |
| 404 | The requested resource was not found. | Check the URL, route registration, API version, host, and deployment environment. |
| 405 | The method is not allowed for that resource. | Compare the method with the API contract and inspect the Allow header. |
| 409 | The request conflicts with the current resource state. | Look for duplicate identifiers, stale versions, or invalid state transitions. |
| 422 | The request is understood but fails validation or semantic checks. | Read field-level errors and compare the payload with the schema. |
| 429 | Too many requests have been sent. | Review rate-limit headers, retry behavior, client concurrency, and backoff. |
| 500 | A general server error occurred. | Correlate the request with application logs and recent code or configuration changes. |
| 502 | A gateway or proxy received an invalid upstream response. | Check upstream health, DNS, TLS, service ports, and proxy configuration. |
| 503 | The service is temporarily unable to handle the request. | Check maintenance state, capacity, health checks, dependency failures, and autoscaling. |
| 504 | A gateway or proxy timed out waiting for an upstream response. | Compare timeout settings and measure database, network, and application latency. |
What to track
When debugging an HTTP error, record enough context to reproduce it. At minimum, capture the request method, complete URL without exposing secrets, timestamp with timezone, environment, response code, response headers, and a redacted response body. For APIs, also record the correlation or request ID if the system provides one.
Use a controlled request
A command-line request helps separate browser behavior from server behavior. Start with headers only:
curl -i -X GET "https://api.example.test/v1/items" \
-H "Accept: application/json"For a JSON request, make the method, content type, and body explicit:
curl -i -X POST "https://api.example.test/v1/items" \
-H "Accept: application/json" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer REDACTED" \
--data '{"name":"example"}'To investigate connection and timing behavior, use verbose output or write a timing format:
curl -v --max-time 20 \
-w "\nDNS:%{time_namelookup} CONNECT:%{time_connect} TLS:%{time_appconnect} TTFB:%{time_starttransfer} TOTAL:%{time_total}\n" \
-o /dev/null "https://api.example.test/health"Do not paste production tokens, cookies, passwords, or personal data into tickets or third-party tools. Redact sensitive headers before sharing a request.
Track the full request path
- Client: Confirm the browser, SDK, proxy, or job is using the intended method, URL, headers, and payload.
- Edge layer: Check CDN, WAF, load balancer, and reverse-proxy rules. These layers may generate responses before the application receives the request.
- Router: Verify host-based routing, API version prefixes, trailing-slash rules, and deployment-specific paths.
- Application: Match the request ID to logs, exception traces, validation messages, and authorization decisions.
- Dependencies: Check databases, queues, identity providers, storage services, and other upstream APIs.
- Response behavior: Inspect caching, content negotiation, compression, retry headers, and the response body.
Cadence and checkpoints
HTTP troubleshooting is most effective when teams track recurring patterns rather than investigating every error in isolation. Review error data monthly or quarterly, depending on traffic and operational risk, and after each significant deployment, infrastructure change, or API version change.
At each review, compare
- Counts and rates for each status-code family, separated by route, method, service, environment, and client.
- Changes in the most frequent 4xx responses, especially validation, authentication, authorization, not-found, and rate-limit errors.
- Changes in 5xx responses by upstream dependency, deployment version, region, and time of day.
- Latency and timeout patterns alongside
502,503, and504responses. - Redirect chains, unexpected location changes, and increases in requests that require more than one redirect.
- Whether logs contain a usable request ID, route name, error category, and safe diagnostic detail.
Keep a small incident record for recurring failures. Include the symptom, affected endpoint, first known time, suspected layer, evidence collected, fix, and a follow-up test. This turns an HTTP response code reference into a working operational habit.
How to interpret changes
A sudden increase in 4xx errors does not always mean the client changed. A deployment may have altered validation rules, route names, authentication scopes, or allowed methods. Check whether the increase is concentrated in one client version, endpoint, region, or release.
A rise in 401 responses often warrants checking token issuance, expiration handling, clock differences, and whether the expected authentication scheme is being sent. A rise in 403 responses points more toward permissions, scopes, policy rules, or resource ownership. Confirm the application’s intended distinction rather than assuming every API uses these codes identically.
For 404, compare the failing URL with the deployed route table and API documentation. A reverse proxy can also remove or add a path prefix, causing a correct application route to become an incorrect public route. For 405, verify the method and, where present, inspect the Allow response header.
For 5xx errors, use timestamps and request IDs to correlate the edge, application, and dependency logs. A 500 may result from an unhandled exception or configuration problem. A 502 often moves the investigation toward the connection between a proxy and upstream service. A 503 may indicate deliberate unavailability, failed health checks, or insufficient capacity. A 504 requires comparing the proxy timeout with the actual duration of database queries, external requests, or application work.
Do not solve an error by simply changing the status code. The response should describe the outcome accurately, remain consistent with the API contract, and give clients a safe, actionable body without exposing stack traces or secrets.
When to revisit
Revisit this reference during a monthly or quarterly API health review, and immediately when a new response pattern appears. Update your internal status-code runbook when you add a gateway, change authentication, introduce a new API version, modify caching, alter timeout settings, or move a service between hosting environments.
Use this practical incident checklist when an API call fails:
- Reproduce the request with the exact method, URL, headers, and a safe sample payload.
- Record the status code, response headers, response body, timestamp, and request or correlation ID.
- Determine whether the response came from the client, edge layer, application, or upstream dependency.
- Check authentication, authorization, routing, method support, validation, and cache behavior for 4xx responses.
- Check logs, health checks, resource limits, DNS, TLS, dependency availability, and timeout values for 5xx responses.
- Compare the failure with the latest deployment, configuration change, traffic change, or API contract revision.
- Retest from the original client and with a controlled
curlrequest. - Document the cause, correction, monitoring signal, and regression test so the next investigation starts with evidence.
For related debugging workflows, see the REST API Testing Guide, the OpenAPI Contract Testing Workflow, and the CI/CD Pipeline Security Checklist. Review this article whenever your status-code distribution, infrastructure, or API contract changes.