When a browser request fails, the visible error is often only the final symptom. This playbook gives you a repeatable path from reproduction to diagnosis: inspect the request, separate browser and backend failures, validate payloads and tokens, replay the call outside the page, and confirm the fix with a focused checklist.
Overview
Debugging an API request is faster when you treat the browser-to-backend path as a series of boundaries. The frontend creates a request, the browser applies security rules, the network carries the request, the server authenticates and validates it, and the server returns a response that the frontend must interpret. A failure at any boundary can look similar in the UI.
Start with the browser’s Network panel rather than changing code immediately. Reproduce the failure with the smallest reliable action, select the failed request, and record its method, URL, status, request headers, response headers, payload, and timing. Preserve the exact environment: browser, origin, API host, route, and account or token state.
Useful browser-based developer tools can shorten the inspection step. A JSON formatter can validate and beautify a response or request body. A JWT decoder can make non-secret token claims readable. A regex tester helps verify client-side validation patterns, while a SQL formatter can make a logged query easier to inspect. A base64 decoder is useful for data transformation, but decoding is not the same as decrypting or validating data.
Use online utilities only with non-sensitive examples. Do not paste live access tokens, passwords, private customer data, API keys, or confidential database queries into a third-party service.
Checklist by scenario
1. Reproduce and capture the failure
- Open DevTools and select the Network panel.
- Enable preservation of the network log if navigation may clear it.
- Clear unrelated requests, then reproduce the problem once.
- Record the request method, full URL, status, initiator, and response time.
- Compare a failing request with a known-good request, if one exists.
For repeatable debugging, copy the request as a command or export a sanitized request definition. A generic replay with curl might look like this:
curl -i -X POST 'https://api.example.test/v1/items' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer REDACTED_TOKEN' \
--data '{"name":"example"}'
Replace the host, headers, and body with values appropriate to your environment. Redact credentials before sharing the command in an issue or chat.
2. Diagnose CORS and preflight failures
If the browser reports a CORS error, inspect whether an OPTIONS request appears before the actual request. This is commonly a preflight check. Look at its status and response headers, including the allowed origin, methods, and request headers. Also check whether credentials are being sent and whether the server’s response is consistent with that choice.
- No preflight response: check routing, proxies, firewalls, and whether the server handles
OPTIONS. - Rejected origin: compare the exact page origin, including scheme, hostname, and port, with the server configuration.
- Rejected header or method: compare the browser’s requested headers and method with the server’s allowed values.
- Credentials problem: review cookie or credential settings on both the frontend request and backend response.
For a deeper walkthrough, use the CORS error troubleshooting guide. Do not treat a permissive development workaround as a production fix without checking the intended origins and authentication model.
3. Inspect authentication tokens safely
First determine where authentication is expected: an Authorization header, a cookie, or another mechanism. Confirm that the request actually contains the expected credential and that the backend receives it through any proxy or gateway.
For a JWT, inspect the header and payload to check non-secret claims such as the issuer, audience, subject, and expiration. A JWT decoder only decodes encoded sections; it does not prove that a token is authentic. Signature validation must happen through the server’s authentication process. Treat every token as sensitive even when its payload is readable, and revoke or rotate credentials if a live token is exposed.
4. Validate payloads and responses
A successful transport does not guarantee a successful application operation. Confirm the request’s content type, field names, nesting, data types, required values, and encoding. Then format the response and inspect the actual error object rather than relying on a generic frontend message.
When a response is malformed, copy a harmless sample into a JSON formatter to identify missing commas, invalid quoting, truncated output, or an unexpected top-level type. If the frontend parses a string as JSON, verify that the server is returning JSON consistently and that the response headers match the body.
5. Replay and isolate
Replay the request outside the browser using a sanitized curl command, an API client, or a backend test. If the replay fails in the same way, focus on the server, route, data, authentication, or network path. If the replay succeeds but the browser fails, focus on origin policy, browser credentials, request construction, caching, or frontend response handling.
Change one variable at a time: method, body, token, origin, or header. This prevents a series of simultaneous edits from hiding the actual cause.
Quick tool comparison
| Tool or feature | Best use | Check before using |
|---|---|---|
| Browser Network panel | Inspect requests, responses, headers, timing, and initiators | Preserve logs and filter to the failing route |
| JSON formatter | Validate and read request or response JSON | Remove sensitive values first |
| JWT decoder | Inspect readable token claims while troubleshooting | Decoding does not verify a signature |
| Regex tester | Test client-side or backend validation patterns | Match the correct regex flavor and flags |
| Base64 decoder | Inspect encoded sample data | Base64 is encoding, not encryption |
| Request replay tool | Separate browser behavior from API behavior | Sanitize copied headers and credentials |
What to double-check
- URL and environment: Verify the scheme, host, port, API version, route prefix, and deployment environment. A frontend can appear correct while pointing to an old or local backend.
- Origin: Compare the exact browser origin with the server’s configured origin. Differences in ports or schemes matter.
- Headers: Check content type, authorization format, custom headers, and proxy-added headers. Header names and values should match the backend contract.
- Cookies: Check whether the request includes cookies, whether the cookie scope is correct, and whether browser privacy settings affect delivery.
- Time: An expired token or timestamp-dependent request can fail even when the code has not changed.
- Database input: If the backend builds a query from request data, inspect logs and parameter binding safely. Format a redacted query for readability rather than copying production secrets.
- Error visibility: Confirm that server logs, gateway logs, and browser logs refer to the same request. A correlation ID can make this comparison easier.
Common mistakes
Blaming CORS for every failed request. CORS usually explains why browser JavaScript cannot read a response; it does not automatically explain a server-side 500 error, an invalid payload, or a refused connection. Inspect the Network panel and server logs together.
Changing the frontend before capturing evidence. Save the failing request details first. Otherwise, a code change may remove the symptom without explaining the cause.
Assuming a decoded token is trusted. Readable claims are useful for diagnosis, but only the server’s validation process should decide whether a token is accepted.
Testing only the happy path. Try missing fields, expired authentication, an empty result, a malformed value, and a slow response in a safe test environment. The frontend should handle each expected error deliberately.
Copying sensitive requests into public tools. Use placeholders and synthetic data. If a credential was pasted or logged, treat exposure as a security event and follow the applicable rotation process.
When to revisit
Use this checklist whenever a frontend connects to a new API, an authentication flow changes, an environment is deployed, a proxy is introduced, or a request begins failing only in production. Revisit it after browser DevTools changes, framework upgrades, API contract changes, and updates to CORS or token configuration.
Before closing an incident, record the failing request, root cause, affected environment, fix, and verification step. Then confirm the fix in the browser and with an independent replay. Add a regression test for the boundary that failed: an API contract test for payloads, an authentication test for token handling, or an integration test for the relevant origin and credentials.
For the next debugging session, print or save this short sequence:
- Reproduce once and preserve the network record.
- Inspect URL, method, status, headers, body, and response.
- Separate CORS, authentication, validation, and server errors.
- Decode or format only sanitized data.
- Replay the request outside the browser.
- Change one variable, verify the fix, and document the cause.
Related workflows can help complete the investigation: review the frontend developer workflow checklist, and use the guides for JSON formatting, JWT inspection, and regex testing when those specific inputs are part of the failing request.