Debugging API requests is one of the most common tasks in modern development — and one of the most frustrating when things go wrong. This guide covers the tools and techniques that will help you diagnose any API issue quickly.
1. Start with the Status Code
Every API response includes an HTTP status code that tells you what happened. Understanding these codes is the first step in debugging:
- 2xx — Success. 200 OK, 201 Created, 204 No Content.
- 4xx — Client error. You sent something wrong. 400 Bad Request, 401 Unauthorized, 403 Forbidden, 404 Not Found, 422 Unprocessable Entity.
- 5xx — Server error. The server broke. 500 Internal Server Error, 502 Bad Gateway, 503 Service Unavailable.
Use our free REST Client to send requests and see the exact status code returned.
2. Inspect Response Headers
Response headers contain critical debugging information that developers often overlook:
- Content-Type — Is the server returning JSON when you expect it? Mismatched content types cause silent parsing failures.
- Access-Control-Allow-Origin — Missing CORS headers cause browser fetch() calls to fail silently.
- X-RateLimit-Remaining — Have you hit a rate limit?
- WWW-Authenticate — Tells you what authentication scheme is required.
Use our HTTP Response Inspector to fetch and display all headers from any public URL instantly.
3. Decode Your JWT Token
If your API uses JWT authentication, a malformed or expired token is the most common cause of 401 errors. Before debugging anything else, decode your JWT to verify:
- The
expfield — has the token expired? - The
audfield — is the audience correct for this API? - The
issfield — was the token issued by the expected authority? - Custom claims — are all required fields present?
Paste your JWT into our JWT Decoder — it shows the header, payload and expiry information in seconds without any login required.
4. Reproduce with cURL
When debugging API issues, always try to reproduce the problem with a raw cURL command. This eliminates variables like browser state, cookies and CORS policies:
curl -X POST https://api.example.com/users \
-H "Authorization: Bearer YOUR_TOKEN" \
-H "Content-Type: application/json" \
-d '{"name": "Alice"}' \
-v
The -v flag shows verbose output including request and response headers. Use our cURL Builder to construct commands visually, or convert cURL to JavaScript fetch for use in your frontend code.
5. Check Your Request Body
400 and 422 errors are almost always caused by an invalid request body. Common mistakes include:
- Sending invalid JSON (use our JSON Validator to check)
- Wrong Content-Type header — must be
application/jsonfor JSON payloads - Missing required fields
- Wrong data types — sending a string where a number is expected
- Extra fields that the API rejects with strict validation
6. Test Webhooks Locally
Debugging webhooks is tricky because they're triggered by external events. Use our Webhook Sender to fire test POST requests to your endpoint from the browser, or tools like ngrok to expose your local server to the internet for live webhook testing.
7. Use the Network Tab
Browser DevTools Network tab is your best friend for debugging API calls made by web applications. Look for:
- Timing — Is the request slow? DNS lookup, connection, TTFB separately
- Preview tab — Formatted response body
- Headers tab — Both request and response headers
- Copy as cURL — Right-click any request to copy as cURL for reproduction
Quick Debugging Checklist
- ✅ Check the status code first
- ✅ Decode your JWT for expiry and claims
- ✅ Validate your request body JSON
- ✅ Inspect response headers for CORS and content-type
- ✅ Reproduce with cURL using -v flag
- ✅ Check rate limit headers
- ✅ Verify authentication scheme matches what the API expects