API Debugging: From a Failed Request to a Verified Fix
Capture what the browser actually sends, then check request format, browser policy and server authentication. Each stage identifies the evidence to inspect and the result to verify.
Start with one recorded failure
In the browser Network panel, record the time, complete URL, method, headers, body, status and response body. Keep the OPTIONS and actual request as separate records, along with any gateway request ID. Replace cookies, authorization values and personal data with test values before sharing. The example.com addresses below are illustrative.
POST https://api.example.com/orders
Origin: https://app.example.com
Content-Type: application/json
quantity=2This request declares JSON but carries form syntax. If the endpoint expects JSON, use {"quantity":2}; if it expects a form, use the documented form media type. A server may return 400, 415 or an application error, so the status alone does not establish the cause.
Jump To Common Incidents
1) Shape Request Inputs
Compare the captured request with the endpoint contract before changing it.
- Check the final URL, redirects and method. Preserve repeated parameters and their order when the API depends on them; do not clean signed URLs before reproducing the failure.
- Compare Content-Type with the actual body bytes. A JSON header does not convert form data into JSON. For browser FormData, let the browser generate the multipart boundary.
- Build a minimal request with test values. Confirm the server received the intended fields; successful local formatting does not prove the endpoint accepts them.
2) Validate Protocol Contracts
Check headers, CORS, and cookie policy consistency across gateway and app.
- If OPTIONS appears, compare Access-Control-Request-Method and Access-Control-Request-Headers with the preflight response. Check whether the actual request was then sent.
- For credentials: include, both the preflight when present and the actual response need the allowed explicit origin and Access-Control-Allow-Credentials: true. A wildcard origin or a successful OPTIONS alone is insufficient.
- For missing cookies, read the browser’s exclusion reason and inspect Domain, Path, Secure, SameSite and credentials mode. SameSite=None; Secure does not override third-party-cookie blocking. Check the final headers after the gateway.
3) Inspect Auth and Payload
Separate readable claims, valid signatures and the service’s authorization decision.
- Use a disposable JWT to inspect iss, aud, exp and nbf. JWT time claims use Unix seconds. Decoding only reads the claims; verify with a trusted key and the expected algorithm, then apply the service’s claim and permission rules.
- For a 200 response that fails JSON parsing, inspect Content-Type and the start of the raw body. A login page or proxy error may be HTML despite the status; fix that response path instead of repeatedly formatting it.
- Compare an expected allowed request with a deliberately invalid credential in the test environment. Record the server error code and request ID; Base64 output or a valid signature alone does not prove access is authorized.
Verify the fix with the same case
Change one variable at a time and repeat the test from the original browser origin. Check the status, media type, returned fields and JavaScript access against the endpoint contract. Also test rejection with invalid credentials or a disallowed origin. cURL can inspect HTTP responses but does not enforce browser CORS.
A POST, payment or write may already have executed even when the browser cannot read the response. Reproduce with test data in a test environment and follow the endpoint’s idempotency rules when retrying. Record the cause, the change and any conditions still unverified.