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.