Decode API responses, CDN errors and gateway failures in one reference
HTTP status codes are the fastest signal in a distributed system: they tell clients whether to retry, surface a form error or page an on-call engineer. Memorising every code between 100 and 599 is unnecessary; understanding families and the handful of codes your platform actually emits saves hours during incidents. This reference groups codes by class, explains typical causes in data and platform work and helps you write runbooks that match what curl, browsers and load balancers already expose in the status line.
Triage workflow
- Capture method, URL, response headers and body from curl or browser devtools.
- Identify the class: 4xx client, 5xx server or 3xx redirect chain.
- Map the exact code here and check whether retry is safe (idempotent GET versus POST).
- If the payload is JSON, validate structure before you blame the network.
Classes that matter for data APIs
2xx means the server accepted responsibility for the semantics you requested — but read the body anyway when exports are asynchronous. 4xx points to caller mistakes: bad query params, expired tokens or schema mismatch. 5xx means fix the service or upstream dependency, not the spreadsheet. 429 and 503 often arrive with Retry-After headers; honour them in batch clients so you do not amplify outages. When debugging encoded query strings, pair this page with the URL Encoder & Decoder and inspect bearer tokens in the JWT Decoder when auth failures look like opaque 401s.
From status line to warehouse retries
Ingest jobs should classify errors: 408 and 504 may be transient network blips worth retry with backoff; 400 and 422 usually need quarantine files and owner notification. Logging the numeric code alongside a correlation id beats logging only “error.” When partners return HTML error pages on 502, store a short hash of the body so you can detect CDN swaps without retaining PII. For JSON error envelopes, paste samples through the JSON Formatter before you attach them to tickets.
Teaching clients and stakeholders
Product managers often conflate “cannot find route” (404) with “not authorised” (401/403). A shared reference reduces slack threads during launches. Document which codes your public API guarantees stable for years versus which are internal implementation details that may change. That distinction keeps mobile apps and ETL scripts from baking in accidental dependencies on generic 500 text.
Retrying safely without making things worse
A retry on the wrong response amplifies an outage instead of recovering from it. Retry the transient server and gateway codes — 502, 503 and 504 — and the rate-limit 429, always with exponential backoff plus jitter so a fleet of clients does not stampede the moment a service recovers. Do not blindly retry 4xx client errors: a 400 or 422 will fail identically every time, and a retried POST without an idempotency key can create duplicate orders or payments. Send an idempotency key on any non-idempotent request you intend to retry and honour Retry-After when the server tells you how long to wait.