Debugging a failing API call

A page shows a spinner forever, a sign-in loops, or a button does nothing. The answer is usually in the requests the browser made. These tools read a capture of them, explain what went wrong and turn the request into something you can run again. A capture holds passwords, cookies and tokens, so everything here stays in your browser.

Take care with secrets. This runs only in your browser: what you enter isn't uploaded, stored or put in a link, and the page is built so that it can't send it anywhere else. Your browser's extensions and other software on your device can still see what's on screen, so use a device you trust and real secrets only when you need to. Disconnecting from the internet once the page has loaded gives the most protection. Use is at your own risk: see the terms.

1. Capture and find the failure

In the browser’s developer tools, open the Network tab, reproduce the problem, then export the requests as a HAR file (right-click in the list of requests and save all as HAR). Chrome and Edge leave out sign-in headers and cookies unless you first turn on Allow to generate HAR with sensitive data (developer tools Settings › Preferences › Network), and step 3 needs them. The file then holds live sign-in details, so treat it like a password and redact it before sending it to anyone (step 6).

Drop it on the HAR Viewer & Redactor. Failed requests (status 400 or over, or 0) are in red; type part of the address in Filter to narrow the list.

2. Read the status

Look the code up in HTTP Codes & MIME Types. The common ones when an API fails:

• 401: no valid sign-in. Check the token (step 3).
• 403: signed in, but not allowed. Check the token’s scope or roles.
• 404 or 405: the wrong address or method.
• 415: the body’s Content-Type isn’t one the server takes.
• 429: too many requests; look for a Retry-After header.
• 0: the browser blocked it, often for CORS or a certificate problem.

3. Check the token

Copy the Authorization header’s value into the JWT Decoder; a leading Bearer is ignored. Check the audience (aud) is this API, the scope allows what you asked, and exp hasn’t passed. What’s inside this JWT? goes through each claim and how to check the signature.

If the sign-in uses SAML instead (a form post with SAMLResponse), paste that value into the SAML Decoder to see the user, the attributes and the times the assertion is valid for.

4. Read the response

Error responses often explain themselves in JSON. Paste the body into JSON Format and Prettify it, or use a JSONPath query such as $.errors[*].message to pull out just the messages.

Some APIs answer in binary instead: gRPC and gRPC-Web (application/grpc-web+proto), Protobuf (application/x-protobuf), CBOR or MessagePack. The Network tab shows these as unreadable characters, and a HAR file keeps them as Base64 in the response’s content.text. Paste that Base64 into the Binary Data Decoder to see the fields and values, error messages included. A gRPC-Web body starts with a 5-byte frame header (a flag byte and a 4-byte length), so if it doesn’t decode, switch The input is to hex and leave out the first ten hex digits.

When the API rejects what you sent (often 400 Bad Request or 422 Unprocessable Content) and doesn’t say why, check the request body against the API’s own description of it. Many APIs publish a JSON Schema for each request, often inside their OpenAPI document. Paste the body into the Data Validator, open Check against a JSON Schema and paste the schema for that request: each field that doesn’t fit is named, such as $.quantity should be a whole number, not text.

5. Make it repeatable

In the browser’s Network tab, right-click the request and Copy as cURL, then paste it into cURL to Code. Choose Python, JavaScript or another language to get the same request as code you can change and run. It also takes a raw HTTP request or a HAR, and can turn either into a curl command.

6. Share it safely

Back in the HAR Viewer, Save the redacted HAR replaces authorization headers, cookies, tokens, passwords and every JWT with REDACTED. Tick Remove response bodies when saving if the responses hold personal data. Send that copy to a colleague or a support team, never the original.