Integration Debugging Playbook

When the API call, webhook, or auth handshake fails at the customer’s edge — the systematic checklist that finds it fast.

Read the status code

401 / 403: Auth. Wrong/expired token, missing scope, or IP not allow-listed. Check the exact header.
404: Wrong URL/base path or the resource isn’t there yet. Sandbox vs prod host?
429: Rate limited. Back off (jitter), check Retry-After, batch requests.
5xx: Their side (or a proxy). Retry idempotent calls; capture request-id; escalate with it.
Timeout / no response: Firewall/egress, DNS, or wrong port. Try curl -v from the deploy host.

Token in the right place: Header vs query vs body. Authorization: Bearer … — exact casing/prefix.
Clock skew: Signed requests / JWT fail if the server clock is off. Sync NTP.
Scopes / audience: Token valid but lacks the scope, or wrong aud for this API.
mTLS / cert: Customer requires a client cert? Verify chain + that it’s actually being sent.

Signature mismatch: Verify over the raw body (not re-serialized JSON); use the right secret + algorithm.
Reachability: Is your endpoint public + TLS? Use their delivery log / a request-bin to confirm arrival.
Duplicates / retries: They retry on non-2xx. Be idempotent; ack fast (2xx) then process async.
Replay window: Reject events older than N minutes to stop replay attacks.

curl from the box: Reproduce from the actual deploy host — not your laptop. Egress rules differ.
Log the request-id: Most APIs return one. It’s your ticket when you escalate to their team.
Binary-search the stack: DNS → TCP/TLS → auth → payload. Confirm each layer before blaming the next.
Diff working vs broken: A Postman call that works vs your code that doesn’t → compare headers byte-for-byte.