API Debugging v1.0.0

API Debugging

A systematic playbook for diagnosing a failing API call, from first symptom to root cause.

When to use

An HTTP request to an API is failing, misbehaving, or returning something unexpected, and the cause is not obvious.

How

Work the layers in order. Do not skip ahead — most API bugs die at layer 1 or 2.

Layer 1: The request itself

• Reproduce with the simplest possible call (curl). Confirm the exact URL, method, headers, and body bytes.
• Check auth: is the credential present, fresh, and in the right header/query slot? Re-read the docs for the exact scheme (Bearer vs Basic vs key param).
• Check encoding: JSON bodies are valid JSON, no smart quotes, correct content-type.

Layer 2: The response, read literally

• Read the status code as what it is: 401 = auth rejected, 403 = auth ok but forbidden, 404 = wrong path or wrong id, 422/400 = payload rejected (read the error body, it usually names the field), 429 = slow down, 5xx = their problem, confirm with a retry.
• Read the full error body. APIs usually tell you the answer; people usually don't read it.
• Compare against the docs: is the field name, nesting, or enum value exactly right?

Layer 3: State and assumptions

• Is the resource id real? Does the referenced object exist, in the right environment (prod vs sandbox)?
• Did something change recently — a deploy, a key rotation, a quota reset, a plan limit?
• Test the same call against a known-good client or the provider's dashboard to split "my code" from "their service."

Layer 4: The wire

• Timeouts and connection drops: retry with backoff, check DNS, check whether a proxy or firewall is in the path.
• Log the raw request and raw response (redact secrets). If you can't see both, you're guessing.

Reporting the bug

When you have the root cause, report: the minimal reproducing request (secrets redacted), the exact response, what the docs say should happen, and which layer the fault is in. That is the whole ticket.

What not to do

• Do not retry blindly without reading the error body first.
• Do not "fix" auth by pasting secrets into chat logs, tickets, or code comments.
• Do not assume the provider is down until layer 3 is exhausted.