API Debugging Tooling — When to Use Which

API bugs rarely announce themselves politely. You get a blank UI, a CORS banner, or a 401 that “worked yesterday.” The fix is often five minutes — once you pick the right inspection surface. This guide maps common symptoms to tools so you stop bouncing between six tabs at random.

The short decision table

Symptom	Reach for	Avoid as first move
“Invalid JSON” / parse errors	JSON formatter + raw body view	Rewriting client code blindly
401 / 403 / weird claims	JWT decoder (header+payload) + server logs	Editing tokens by hand in prod
Works in Postman, fails in browser	Browser Network + CORS/cookie checks	Only Postman forever
Intermittent staging failures	HTTP client collections + retry logs	One-off curl you cannot replay
Suspected proxy mutation	mitmproxy / Charles / browser HAR	Guessing CDN magic

JSON formatter: contracts and trailing commas

When the console says Unexpected token, paste the raw response into a formatter before touching React state. You are looking for:

• Trailing commas / single quotes (not JSON)
• BOM or HTML error pages served as application/json
• Huge minified payloads that hide the field you renamed

Keep a golden pretty-printed fixture per endpoint in the repo. Diff the formatter output against the fixture when serializers drift. Online formatters are fine for non-sensitive payloads; for customer data, prefer a local tool or editor.

JWT decoder: read claims, do not “verify” in the browser casually

Decode to inspect iss, aud, exp, sub, and custom roles. Check clock skew if exp looks “soon” but the server rejects. Remember: decoding is not validation — anyone can read a JWT payload. Signature checks belong on the server (or a trusted local verifier with the right key material).

Never paste production refresh tokens into random websites. Prefer a local decoder or your own JWT tool on a machine you control, and redact before screenshots.

HTTP clients: Postman, Insomnia, Bruno, curl

Use a collection when:

• You need repeatable auth flows (OAuth, API keys)
• QA must share exact requests
• You are bisecting which header matters

Export collections into git when they encode the contract. Prefer environment variables for hosts and secrets. curl remains the lingua franca in tickets:

curl -sS -D - -o body.json \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  "https://api.example.com/v1/items?limit=2"

If Postman succeeds with its hidden cookie jar and your SPA fails, the bug is browser storage/CORS/SameSite — not “the API is fine” in the absolute sense.

Browser Network panel: the source of truth for SPAs

Filter by Fetch/XHR. Check:

1. Request URL (prod vs staging mixups)
2. Preflight OPTIONS status and ACAO headers
3. Actual status on the real request (not only the console’s CORS summary)
4. Request payload vs what you think you sent
5. Whether a Service Worker answered from cache

Copy as cURL from DevTools when filing bugs — it captures headers humans forget.

Diff and schema tools

When field names drift (userId vs user_id), a structured diff of two JSON responses beats staring. OpenAPI diff / schema validators catch removed fields before mobile clients ship. Pair with contract tests so the formatter is not your only CI.

Proxy capture for “middleware ate my header”

Mobile apps, desktop Electron, and misbehaving gateways need a capturing proxy. Use it to see the on-wire request after corporate SSL inspection or API gateways. Disable once done; leaving a system proxy on is how you create new Heisenbugs.

A sane debugging order

1. Reproduce with the smallest HTTP request (curl/client).
2. Pretty-print JSON; confirm shape and status.
3. If auth-related, decode JWT claims and compare to server expectations.
4. If only the browser fails, Network + CORS/cookies.
5. Only then change application code.

Tooling hygiene

• Store example requests without live secrets
• Rotate any token that hit a shared chat
• Prefer local formatters/decoders for sensitive payloads
• Document “known staging quirks” next to the collection

Bottom line

Formatters show shape, JWT decoders show claims, HTTP collections show intent, and the browser Network panel shows reality. Match the tool to the symptom and you spend minutes on APIs instead of afternoons arguing with ghosts.

Closing notes

Keep this page next to your incident runbook. The value is a reusable mental model for the next outage or launch — not a checklist you read once and forget. Trim personal notes down to the three steps you actually used last time; short runbooks get followed, long ones get skipped under pressure.