2.2Interpreting HTTP responses

Troubleshooting API integrations is not about guessing "server's fault vs. client's fault." An HTTP response carries three sources of information—status code, headers, and body—and cross-referencing them with the request you sent and what the docs say isolates most causes mechanically. This section nails what the common codes (401/403/404/429/5xx) reveal about "whose problem and what kind," building the ability to derive the next action from the response.

2.2.1Code classes and common codes

• The hundreds digit reveals the class: 2xx = success (200 OK retrieved, 201 Created created, 204 No Content succeeded with no body), 3xx = redirect, 4xx = client-side error (something wrong in the request you sent), 5xx = server-side failure (your request is broadly fine but the server failed). Whether it is 4xx or 5xx changes the first move: "fix myself" vs. "server-side/retry."
• Distinguishing the 4xx codes is the crux in practice: 400 = malformed request (bad JSON or parameters), 401 Unauthorized = unauthenticated (missing/invalid credentials or wrong scheme), 403 Forbidden = authenticated but lacking permission (scope/role), 404 Not Found = resource/URL absent (including a wrong endpoint path), 429 Too Many Requests = rate exceeded. 401 vs. 403—"identity failed" vs. "permission failed"—call for entirely different remedies.
• 5xx (500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable) is generally a server-side problem. Fixing your request often will not help, so a retry after a delay or contacting operations is the practical move. That said, your payload could be crashing the server, so it is worth a glance at whether you just changed a value.

2.2.2Reading headers and body together

• The response headers carry hints for the next move: Retry-After on a 429 says how many seconds to wait, WWW-Authenticate on a 401 names the required scheme, Content-Type gives the body format, and rate headers like X-RateLimit-Remaining show remaining calls. Reading headers tells you the wait time or the missing auth without guessing.
• The response body (usually JSON) holds human-readable error detail, e.g., {"error":"invalid_token","message":"The access token expired"}. Even when the status is 401, reading the body's invalid_token/expired pins it down uniquely to "token expired -> refresh." The standard practice is to classify broadly by the code and confirm the specific cause from the body.

Suppose a nightly batch that hits an inventory API is reported to fail intermittently. The logs mix three responses. The first is 403 Forbidden with body {"error":"insufficient_scope","message":"token lacks inventory:write"}. The second is 429 Too Many Requests with header Retry-After: 30. The third is 404 Not Found for the request URL GET /v1/itens/1234. These have entirely different causes, and uniformly "add more retries" solves none of them. First, the 403 means authentication itself succeeded (it is not 401) and the body explicitly states the token's insufficient scope—the fix is to issue a token holding inventory:write (or ask an admin to grant the role); retrying stays 403 forever. The 429 is a rate overage, and Retry-After: 30 explicitly says "wait 30 seconds," so retry with exponential backoff (or the indicated wait); tightening the retry interval here pours fuel on the fire. The third, 404, looks like a missing server resource, but cross-referencing the URL with the docs shows the correct path is /v1/items/1234—itens is a typo, a client-side endpoint error. The lesson: even for the same "failure," isolating by code class (4xx/5xx) -> specific code (403/429/404) -> header/body detail -> your request uniquely determines a per-case action (re-issue scope, back off, fix the URL). Push everything through "just retry" without reading the response and the 403 and 404 never heal while the 429 gets worse.

2.2.3Section summary

• The code class sets the first move: 2xx success / 4xx = fix your request / 5xx = server-side, retry or contact operations
• Distinguishing 4xx is key: 401 = unauthenticated, 403 = authenticated but lacking permission, 404 = not found, 429 = rate exceeded; do not confuse 401 with 403, or a URL typo behind 404
• Cross-reference code + headers (Retry-After/WWW-Authenticate) + JSON body + your request to fix the next action without guessing