2026-05-30 · 7 min read · Rahul Chitturi
- api
- debugging
API incidents rarely need genius—they need a repeatable checklist. Before diving into source code, validate the shape of what the wire actually returned versus what the client expected.
1. Validate syntax
Paste the raw response into a JSON validator. HTML error pages and truncated gzip bodies often masquerade as JSON. If parsing fails, inspect status codes and Content-Type headers first.
2. Compare schemas
Diff the failing response against a known-good sample. Strip volatile fields (timestamps, request IDs) so you see structural drift, not noise.
3. Check types
Type mismatches are the leading cause of silent UI bugs in strongly typed clients.
- Numbers sent as strings ("42" vs 42)
- Null vs missing keys
- Arrays where objects were expected
- Epoch seconds vs milliseconds
4. Auth layer
Decode JWTs to inspect exp and aud claims. An expired token often returns 401 with a generic body that sends you on a wild goose chase through business logic.