8 min read

Common API Debugging Techniques

A step-by-step approach to debugging failing API requests: status codes, headers, payloads, authentication, encoding, and timing.

1. Read the status code first

The status code tells you which layer to investigate. A 4xx points at the request you sent; a 5xx points at the server or something between you and it. Look up unfamiliar codes before changing code.

2. Inspect the exact request

Open your browser's Network panel or use curl -v to see the method, URL, headers, and body that were actually sent. Many bugs are a missing Content-Type: application/json header or a body that was never serialized.

curl -v -X POST https://api.example.com/items \
  -H "Content-Type: application/json" \
  -d '{"name":"test"}'

3. Validate the payload

Paste the request and response bodies into a JSON formatter. Invalid JSON, a field nested one level too deep, or a number sent as a string are much easier to see when the document is indented.

4. Check authentication

For 401 and 403 responses, decode the bearer token and check exp, aud, and scopes. An expired token or one issued for a different audience is a very common cause.

5. Check encoding and timing

Query parameters with spaces, & or non-ASCII characters must be URL-encoded. Timestamps in the wrong unit (milliseconds vs seconds) cause expiry and filtering bugs. Finally, compare a working and failing request side by side with a diff to find the one difference.

Try the JSON Formatter