# 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.