HTTP status codes are useful clues, not complete diagnoses. This reference explains what common API responses mean, what to check next, when retries are safe, and which signals to monitor during recurring integration reviews or incident response.
Overview
When a cloud API request fails, begin with the response status, then examine the request path, authentication context, payload, timing, and service logs. A status code usually identifies the broad class of problem: the client request, the authentication decision, a resource conflict, throttling, or a server-side failure.
Do not assume that every response came from the application. A reverse proxy, API gateway, load balancer, web application firewall, or service mesh may reject a request before it reaches the API. Compare the response headers, body format, correlation ID, and access logs to determine which layer produced the error.
For a repeatable REST API debugging process, record the exact method and URL path, request ID, status code, response time, authenticated subject or service identity, and a safe representation of the request payload. Avoid logging access tokens, passwords, API keys, or sensitive business data.
For related workflows, see the API debugging workflow for cloud applications and the production readiness checklist for cloud-native web applications.
What to track
The table below is a practical starting point for understanding common HTTP status codes and choosing the next diagnostic step.
| Status | Meaning | What to check next |
|---|---|---|
| 200 OK | The request completed successfully and returned a response. | Confirm the response schema, business result, and pagination or filtering behavior. |
| 201 Created | A resource was created. | Check the returned resource identifier and the Location header if supplied. |
| 202 Accepted | The request was accepted for processing, but work may not be complete. | Find the job status endpoint, callback, or polling guidance. Do not treat acceptance as completion. |
| 204 No Content | The request succeeded without a response body. | Ensure the client does not attempt to parse an empty body as JSON. |
| 400 Bad Request | The server could not process the request as submitted. | Check syntax, required parameters, query encoding, headers, and the documented error body. |
| 401 Unauthorized | The request lacks valid authentication credentials. | Check whether the credential is missing, expired, malformed, aimed at the wrong issuer or audience, or sent in the wrong header. |
| 403 Forbidden | The server understood the identity but will not authorize the operation. | Check scopes, roles, tenant boundaries, resource ownership, policy rules, and network restrictions. |
| 404 Not Found | The target resource or route was not found. | Verify the base URL, API version, path parameters, deployment, tenant, and resource identifier. |
| 405 Method Not Allowed | The route exists, but the HTTP method is not supported there. | Compare the method with the API contract and inspect the Allow header when available. |
| 409 Conflict | The request conflicts with the current state of a resource. | Look for duplicate identifiers, optimistic-locking failures, or a state transition that is no longer valid. |
| 412 Precondition Failed | A required request precondition was not met. | Check conditional headers such as If-Match and whether the resource version changed. |
| 413 Content Too Large | The request body exceeds a configured limit. | Check gateway, proxy, and application limits, then reduce or upload the payload differently. |
| 415 Unsupported Media Type | The server does not support the submitted representation format. | Verify Content-Type, serialization, character encoding, and the endpoint contract. |
| 422 Unprocessable Content | The request is well-formed but fails semantic or validation rules. | Inspect field-level errors, allowed values, formats, and cross-field constraints. |
| 429 Too Many Requests | The client has exceeded a rate or concurrency limit. | Read Retry-After if present, reduce request pressure, and review quotas and backoff behavior. |
| 500 Internal Server Error | The service encountered an unexpected condition. | Use the correlation ID to inspect application logs, recent deployments, and dependency failures. |
| 502 Bad Gateway | A gateway or proxy received an invalid response from an upstream service. | Check upstream health, DNS, TLS, connection resets, and gateway-to-service configuration. |
| 503 Service Unavailable | The service is temporarily unable to handle the request. | Check maintenance, capacity, health checks, overload protection, and dependency availability. |
| 504 Gateway Timeout | A gateway did not receive an upstream response within its time limit. | Compare gateway and application timings, then inspect slow queries, downstream calls, and queue depth. |
Status meanings can be shaped by framework defaults and cloud gateway configuration. Treat the response body and service documentation as part of the contract rather than relying on the numeric code alone.
Cadence and checkpoints
Use a short diagnosis flow when a request fails:
- Can the request reach the intended endpoint? Verify DNS, the scheme, host, port, API version, route, and HTTP method.
- Is the failure client-side or server-side? A 4xx response usually requires checking the request, identity, or resource state. A 5xx response usually requires examining the service or an upstream dependency, although gateway and client configuration can still be involved.
- Is the identity valid and authorized? Compare 401 and 403 carefully. For token-based systems, inspect claims safely with a trusted local workflow or the guidance in this JWT decoder guide; never paste production secrets into an untrusted tool.
- Is the payload valid? Validate JSON syntax, required fields, data types, content type, size, and business rules. A JSON formatter and validator workflow can make nested error responses easier to inspect.
- Is the failure temporary? Check 429, 502, 503, and 504 responses alongside latency, retry headers, dependency health, and recent changes.
Review these signals at least monthly for important integrations and more deliberately during a quarterly reliability review. Track the count and rate of each status family, endpoint, caller, deployment version, tenant or region where appropriate, latency percentiles, timeout volume, retry volume, and the percentage of errors with a usable correlation ID.
Use structured logs with fields such as timestamp, request_id, trace_id, http_method, route_template, status_code, duration_ms, service, upstream_service, client_type, deployment_version, and a redacted error_type. Logging the route template instead of a raw URL helps prevent high-cardinality metrics caused by unique IDs.
How to interpret changes
A rising 401 rate often points to credential expiry, a clock problem, an issuer or audience mismatch, or a client deployment that changed header handling. A rising 403 rate more often suggests altered permissions, scopes, tenant policy, or resource ownership. These are not interchangeable fixes: refreshing a token will not resolve a missing authorization grant.
A 400 or 422 increase after a client release suggests a contract, serialization, or validation change. Compare a known-good request with a failing request and inspect the first deployment or configuration change associated with the increase. If the response contains field-level details, preserve those details in a safe diagnostic view rather than reducing every validation error to “request failed.”
For 429 responses, distinguish request-rate limits from concurrency or quota limits. Apply bounded exponential backoff with jitter where the operation is safe to repeat, respect Retry-After when provided, and avoid synchronized retries from every worker. A retry should not hide a capacity problem or turn a brief outage into sustained load.
Before retrying 500, 502, 503, or 504, determine whether the operation is idempotent. Reads are generally easier to retry than writes, but the API contract is decisive. For a create or payment-like operation, use an idempotency key or another server-supported deduplication mechanism when available. For updates, use version checks where appropriate so a retry does not overwrite a newer change. Record the original request ID and retry attempt number so operators can connect the events.
Compare error-rate changes with latency and dependency signals. A stable 5xx rate with sharply increasing latency may indicate saturation or a slow upstream. A sudden 404 increase after a deployment may indicate an incorrect base path or version route rather than missing business data. A status-code chart becomes useful when paired with release markers, trace data, and representative request samples.
When to revisit
Revisit this reference during every significant API or infrastructure change, including authentication-provider changes, gateway migrations, route or schema updates, retry-policy changes, new rate limits, and major framework upgrades. Also review it when recurring dashboards show a new error pattern or when support teams report failures that do not map cleanly to an existing runbook.
On a monthly or quarterly cadence, sample the most frequent 4xx and 5xx responses. Confirm that each has an owner, a documented first check, a safe retry policy, and a useful alert or dashboard. Test that correlation IDs survive the gateway, application, and upstream calls. Verify that logs still redact secrets and that error responses do not expose internal implementation details.
Keep a small change record: the date reviewed, endpoints covered, status-code patterns observed, known gateway behavior, and actions assigned. When a cloud platform or API framework changes its defaults, retest representative requests rather than assuming existing behavior remains unchanged.
For the next review, choose one high-volume endpoint and answer five questions: Which statuses are normal? Which statuses require action? Which failures are safe to retry? Which fields identify the failing layer? Who owns the next investigation? This turns an HTTP status-code reference into an operational tool for dependable cloud API debugging.
