A Practical Checklist for Debugging a Broken API Request (With Free Browser Tools)
You send a request. You get a 401 . Or a 400 . Or an empty response and a vague error. Most API bugs come from a small set of causes: a malformed token, bad encoding, wrong headers, or a network problem. The trick is checking them in a sensible order instead of guessing. Here's the checklist I use, with code for each step. Some steps are quicker with a browser utility than with a throwaway…
Debugging an API request can be a frustrating task, especially when you receive an error like a 401, 400, or an empty response. The root causes of most API bugs are relatively simple, such as a malformed token, bad encoding, incorrect headers, or network issues. To efficiently troubleshoot these problems, follow this checklist:
1. Reproduce the request using cURL: Start by creating a minimal, reproducible request using cURL, a command-line tool. This will allow you to share the request and re-run it easily. Use the -i flag to print the response headers, which may be crucial for further investigation. Once you have a working cURL command, it's straightforward to convert it into your chosen programming language.
2. Inspect the status code: Don't rely solely on `res.ok` to determine the success of your request. The actual status code provides more information about the issue. For example, a 400 means the request was malformed, while a 401 indicates authentication failure. You can use an HTTP status code checker to quickly understand the meaning behind unfamiliar status codes, and always log the response body when an error occurs.
3. Decode JWTs: If you receive a 401 status code accompanied by a Bearer token, double-check the token before blaming the server. A JWT consists of three Base64URL-encoded parts separated by dots: header.payload.signature. You can decode the first two parts locally using a simple JavaScript function. Pay attention to the expiration (exp), audience (aud), issuer (iss), and not before (nbf) fields, as they can often reveal the cause of the error.
4. Verify encoding: Encoding errors can be subtle but persistent. Ensure that query parameters utilize proper URL encoding and that special characters are correctly encoded. URLSearchParams can help avoid common mistakes. Additionally, check Base64 encoding in Basic auth headers and other payload sections. Use an encoder/decoder tool for quick verification.
By methodically following this checklist, you can quickly narrow down the source of API request errors and resolve them efficiently. Remember to never paste production secrets or live tokens into online tools; instead, use test values or decode locally.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
