How to Debug an API Request

Step by step

1. Read the status code first

   A 4xx means the request was wrong; a 5xx means the server failed handling it. That single distinction decides whether you are debugging your call or reporting a bug. 401 is unauthenticated, 403 is authenticated but not permitted, 404 may be a wrong path or a resource you cannot see, 422 usually means the body parsed but failed validation.

2. Check the response headers

   Paste the raw block into a header parser. Look for Retry-After on a 429, WWW-Authenticate on a 401, and Content-Type — a JSON parse error is often an HTML error page arriving where you expected JSON.

3. Confirm the URL is what you think

   Parse it. A missing trailing path segment, a query parameter that was never encoded, or a request to the wrong environment are all invisible in code and obvious once the URL is split apart. Check for a redirect too: a POST that gets redirected may arrive as a GET with no body.

4. Decode the token if authentication failed

   For a 401, decode the JWT and check exp first — an expired token is the most common cause by a wide margin. Then check iss and aud match what the API expects. Remember JWT timestamps are seconds, not milliseconds.

5. Validate the request body

   Only once transport and auth are ruled out. Format the JSON to confirm it is well formed, then validate it against the endpoint's schema if one is published. A 422 with a vague message usually resolves into a single wrong type or missing field.

6. Diff a working request against the failing one

   When everything looks correct, capture a request that works and compare the two payloads field by field. The difference is usually somewhere you were not looking, and a diff finds it faster than reading both.

Example

Working outside in: three cheap checks before touching the payload.

POST /v1/orders
→ 401 Unauthorized

1. Status 401 → authentication, not payload
2. Headers → WWW-Authenticate says why
3. Decode token → exp in the past
4. Refresh the token; payload untouched

Frequently asked questions

• HTTP Header Parser Turn a raw header block into a readable table. In your browser
• HTTP Status Code Reference Search every HTTP status code and what it means. In your browser
• JWT Decoder Read a JSON Web Token header, payload and expiry. In your browser
• JSON Formatter Beautify, validate and sort JSON with precise error messages. In your browser
• JSON Schema Validator Check a JSON document against a JSON Schema and see every failure. In your browser
• URL Parser Split a URL into its scheme, host, path, query and fragment. In your browser
• JSON Diff Compare two JSON documents and see exactly what changed. In your browser

• How to Decode a JWT Read the header and payload of a JSON Web Token, check its expiry, and understand why decoding is not verifying.
• How to Check HTTP Redirects Trace a URL through every hop to its destination, and tell a permanent redirect from a temporary one.
• How to Format JSON Turn minified or broken JSON into something readable, and fix it when it will not parse.