HTTP API Error Troubleshooting Reference: Diagnose Status Codes, Headers, and Response Bodies

Overview

API errors usually fall into a small number of troubleshooting paths: the request is invalid, the caller is not authenticated or authorized, traffic is being limited, an intermediary is changing the request, or the server cannot complete the operation. A reliable investigation separates those paths before changing code or increasing retry counts.

Start by preserving the complete failure. Record the HTTP method, URL without secret query parameters, request headers that are safe to share, status code, response headers, response body, elapsed time, and any provider request ID. Also note whether the failure occurs consistently, only for one resource, or only under load.

Do not treat every non-success response as interchangeable. A 400 usually calls for request validation. A 401 points to missing or invalid authentication, while a 403 generally requires an authorization or policy check. A 429 requires rate-limit handling. A 5xx response may be transient, but it can also expose a persistent server-side or integration problem.

For a deeper workflow covering request traces and retry behavior, see the HTTP API Error Debugging guide.

Checklist by scenario

1. The request returns a 4xx client error

Use this path when the server received the request but rejected its format, identity, permissions, or parameters.

• 400 Bad Request: Compare the payload with the API schema. Check required fields, data types, enum values, nesting, content encoding, and date or number formats. Inspect the response body for a field-level validation message.
• 401 Unauthorized: Confirm that the expected authentication header is present and correctly formatted. Check token expiration, the selected environment, credentials loaded by the process, and whether a proxy or SDK removed the header. A token can be structurally valid but still expired or issued for a different audience.
• 403 Forbidden: Verify the identity's role, scopes, tenant or project context, resource ownership, and network policy. Do not assume that refreshing credentials will fix an authorization failure.
• 404 Not Found: Check the base URL, API version, path spelling, resource identifier, and environment. Some APIs intentionally return 404 when a caller is not allowed to learn that a resource exists, so compare behavior with a known-accessible resource.
• 405 Method Not Allowed: Confirm the HTTP method and inspect the Allow response header when present. A route that accepts POST may not accept PUT or PATCH.
• 409 Conflict: Look for duplicate identifiers, optimistic-locking failures, state transitions, or concurrent updates. Retrieve the current resource before deciding whether to retry or reconcile.
• 415 Unsupported Media Type: Check Content-Type, the serialized body, and whether the endpoint expects JSON, form data, multipart data, or another format.

2. The request returns 429 Too Many Requests

First identify whether the limit is tied to an account, token, IP address, endpoint, concurrency level, or provider-wide condition. Inspect headers such as Retry-After and any documented limit or reset indicators. Respect an explicit retry interval; otherwise use bounded exponential backoff with jitter.

Make retries safe. Automatically retrying a read is usually simpler than retrying a create or payment-like operation. For state-changing requests, use an idempotency key when the API supports one, or confirm the operation's result before sending it again. Also reduce avoidable traffic by caching stable reads, paginating correctly, and preventing multiple workers from repeating the same request.

3. The request returns a 5xx server error

For 500, 502, 503, and 504, compare the failure across endpoints, payloads, regions, and clients. A 502 often suggests a gateway or upstream connection problem; a 503 may indicate temporary unavailability; a 504 commonly means an intermediary did not receive a response within its timeout. These interpretations are useful clues, not proof of the exact cause.

Capture the provider's request or trace ID, timestamp, and response headers. Retry only when the operation is safe and the failure may be transient. Set a maximum attempt count and an overall deadline so a failing dependency does not hold application workers indefinitely. If the same request fails repeatedly, stop retrying blindly and escalate with a minimal reproducible example.

4. The client reports a timeout or connection error

Separate connection establishment from response waiting. DNS failures, TLS negotiation errors, connection resets, and read timeouts point to different layers. Test name resolution, certificate validation, proxy settings, firewall rules, and egress access from the same runtime environment as the application.

Check whether the client library has separate connect, read, and total timeouts. A generous total timeout can still hide a short read timeout, while an unlimited timeout can exhaust worker capacity. Compare a direct request from the host with a request from the application container or Kubernetes pod. If the application runs in Kubernetes, pod status and network behavior may provide useful context; the Kubernetes troubleshooting guide covers related pod-level checks.

5. The browser and command-line client behave differently

Browsers may add an Origin header and enforce CORS, while command-line tools do not. Compare the actual method, headers, URL encoding, cookies, redirects, and preflight requests. A browser failure may be a frontend policy issue even when the API itself returns a valid response to a server-side client.

What to double-check

Inspect the complete response

Use a verbose request while redacting secrets:

curl --verbose --request GET \
  --url 'https://api.example.test/v1/items?limit=10' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer REDACTED'

For a JSON request, make the content type and body explicit:

curl --verbose --request POST \
  --url 'https://api.example.test/v1/items' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer REDACTED' \
  --data '{"name":"example"}'

Review the status line, redirect behavior, response headers, and body together. Useful headers can include Location, Retry-After, WWW-Authenticate, cache indicators, correlation IDs, and server timing information. Avoid logging authorization headers, cookies, API keys, or sensitive request bodies.

Check the request transformation path

• Compare the request generated by the SDK with the request documented by the API.
• Confirm that URL encoding has not changed reserved characters, spaces, or Unicode values.
• Check whether a reverse proxy rewrites the path or strips headers.
• Verify that JSON serialization did not omit null, empty, or false-valued fields that the API expects.
• Confirm the client is calling the intended host, region, version, and environment.

When inspecting encoded parameters or payload fragments, use a trusted local or approved developer tool and avoid pasting production secrets into public utilities. A JSON formatter can help read a response, but formatting does not validate its business meaning.

Compare a known-good request

Create the smallest request that should succeed. Use one resource, one authentication method, and a minimal payload. Then add optional fields, filters, pagination, or concurrency one change at a time. This turns a vague API failure into a controlled comparison.

Common mistakes

• Retrying every error: Retrying a malformed request, expired credential, or forbidden operation adds noise and may increase rate limiting.
• Logging secrets to diagnose headers: Capture header names and safe metadata, but redact tokens, cookies, API keys, and personal data before sharing logs.
• Looking only at the status code: The response body and correlation header often provide the most actionable detail.
• Changing several variables at once: Switching SDKs, credentials, payloads, and environments simultaneously makes the result difficult to interpret.
• Assuming a 404 proves the resource is absent: Check the URL, permissions, tenant context, and API version before deleting or recreating anything.
• Using a formatter as a validator: Well-formatted JSON can still contain the wrong schema, types, permissions, or business state.
• Ignoring proxy and redirect behavior: A redirect can change where credentials are sent, and an intermediary can alter methods, headers, or timeout behavior.
• Sharing an incomplete incident report: Include a timestamp, environment, sanitized request shape, response details, attempt count, and provider request ID so another engineer can reproduce the issue.

When to revisit

Revisit this checklist whenever an API provider changes its version, authentication model, proxy path, client library, retry policy, or response schema. It is also worth reviewing before seasonal planning cycles, major releases, migrations, and changes to worker concurrency or deployment environments.

Keep a short runbook for each important integration. Record the expected status codes, safe retry conditions, timeout values, idempotency approach, required scopes, rate-limit signals, and escalation fields. Test the runbook with a controlled failure rather than waiting for a production incident.

During an incident, take these actions in order:

1. Save a sanitized example of the failed request and full response.
2. Classify the failure as request, authentication, authorization, rate limit, intermediary, server, or timeout related.
3. Compare it with a known-good request from the same environment.
4. Apply the narrowest safe correction or bounded retry.
5. Record the result, request ID, and any change made.

This process keeps HTTP API error handling evidence-based and repeatable. It also gives application, platform, and provider teams a shared vocabulary for resolving failures without exposing sensitive data or masking a persistent problem with endless retries.