How to Debug API Requests: A Repeatable Workflow with JSON Formatters, JWT Decoders, and API Testing Tools

Overview

When an API request fails, the visible error is often only the final symptom. A 401 response may come from a missing header, an expired token, an incorrect audience claim, or a request sent to the wrong environment. A 400 response may indicate invalid JSON, a wrong data type, a missing field, or a mismatch between the endpoint contract and the payload.

A reliable debugging workflow narrows the problem from the outside in:

1. Confirm the request is going to the intended URL with the intended HTTP method.
2. Inspect query parameters, path parameters, and URL encoding.
3. Compare request headers with the API’s requirements.
4. Format and validate the JSON body.
5. Inspect authentication tokens without exposing secrets.
6. Read the status code and response body together.
7. Reproduce the smallest failing request in an API testing tool or command-line client.

Browser developer tools, a JSON formatter, a JWT decoder, an HTTP client, and a small set of code snippets are usually enough for this process. Online developer tools can make inspection faster, but sensitive production credentials and personal data should be removed before using a browser-based utility.

For a broader reference, see the Online Developer Tools Toolkit. If the failure occurs only in a browser, the guide to CORS errors is a useful next step.

Checklist by scenario

Scenario 1: The request never reaches the expected endpoint

Start with the complete request URL. Check the scheme, hostname, port, API version, path, and query string. A frontend application may be using a development base URL while the API client is using a staging URL. Also check for a trailing slash, a duplicated path segment, or a path parameter that was not substituted.

• Confirm the HTTP method: GET, POST, PUT, PATCH, or DELETE.
• Inspect query parameters for missing values and incorrect encoding.
• Use the browser Network panel or an API testing helper to copy the request exactly.
• Check whether a redirect changed the destination or method behavior.

When building URLs in JavaScript, encode values rather than concatenating raw user input:

const params = new URLSearchParams({
  search: 'red shoes',
  page: '2'
});

const url = `/api/products?${params.toString()}`;

This produces URL-safe parameter encoding and makes the final request easier to inspect.

Scenario 2: The server returns 400 or 422

These responses commonly point to a request contract problem. First, copy the request body into a JSON formatter. Valid JSON requires double-quoted property names and string values, no trailing commas, and correctly escaped characters.

const payload = {
  email: 'dev@example.test',
  preferences: {
    alerts: true
  }
};

const response = await fetch('/api/profile', {
  method: 'PATCH',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(payload)
});

Compare the formatted body with the API documentation or a known working request. Pay particular attention to numbers versus strings, Boolean values versus quoted text, nullable fields, date formats, and whether an array is required instead of a single object. For difficult escaping problems, review JSON escaping guidance.

Do not stop at the status code. Read the response body, which may identify a field, validation rule, or expected format. If the body is compressed or minified, format it before interpreting it.

Scenario 3: The server returns 401 or 403

Separate authentication from authorization. A 401 response generally means the server could not accept the supplied identity credentials. A 403 response may mean the identity was accepted but does not have permission for the requested operation. The exact behavior depends on the API, so treat this as a diagnostic direction rather than a universal rule.

• Confirm the authorization header is present and uses the expected scheme, often Bearer.
• Check for accidental whitespace, a truncated value, or a token from the wrong environment.
• Verify that the token has not expired and that its relevant claims match the API.
• Check required scopes, roles, tenant identifiers, or resource ownership.

A JWT decoder can help inspect the token’s header and payload. Decoding is not the same as verifying: the decoded contents do not prove that the signature is valid. Never paste a live production token into an untrusted tool. Use a redacted or locally generated token when possible, and treat the token as a credential even if it is only being decoded.

Scenario 4: The response is successful but the data looks wrong

A 200 or 201 response does not guarantee that the application received the intended result. Format the response JSON and compare its structure with the code that consumes it. Check whether the client expects data.items while the API returns items, or whether pagination metadata is outside the array.

• Inspect the response Content-Type.
• Check whether the API returns cached, filtered, or paginated data.
• Compare IDs and timestamps with the database or source system where appropriate.
• Confirm that a successful empty result is not being mistaken for a failed request.

Scenario 5: It works in an API client but fails in the browser

Compare the two requests line by line. Browser requests are subject to origin rules, preflight requests, cookie policies, and restrictions on certain headers. Inspect the browser Network panel for an OPTIONS request, its response headers, and the actual request that follows. If the preflight fails, the application request may never be sent. Keep the CORS investigation separate from JSON or authentication debugging so that each layer is tested independently.

What to double-check

Before changing application code, capture a small evidence set. Record the method, URL without secrets, relevant request headers, redacted body, status code, response headers, response body, and timestamp. This prevents repeated tests from becoming guesswork.

Headers deserve special attention. Content-Type describes the format being sent, while Accept describes the response format the client prefers. They are not interchangeable. Cookies, custom tenant headers, correlation IDs, and conditional headers can also change server behavior.

Authentication needs a separate safety check. Remove or mask values such as API keys, session cookies, refresh tokens, and authorization headers before sharing a request. A decoded JWT may contain email addresses, internal identifiers, or permissions. Treat those claims as sensitive even when the token payload is readable.

Finally, reduce the request. Remove optional fields, use a known test record, and send the smallest payload that still reproduces the problem. If the reduced request succeeds, add fields back one at a time. This approach is often faster than inspecting a large application trace.

Common mistakes

• Reading only the status code: The response body often contains the precise validation or permission detail.
• Formatting invalid JSON without fixing its source: A formatter can reveal syntax errors, but the code constructing the payload still needs correction.
• Assuming a decoded JWT is trustworthy: Decoding exposes claims; it does not validate the signature or authorize the request.
• Changing several variables at once: Replacing the token, payload, endpoint, and headers together removes the evidence needed to identify the cause.
• Testing only through the application UI: A minimal request in an API client or command-line tool helps distinguish API behavior from frontend behavior.
• Ignoring environment differences: Hostnames, credentials, API versions, feature flags, and seed data may differ between local, test, and production environments.
• Sharing raw request logs: Logs can contain credentials and personal data. Redact before copying them into tickets, chats, or online developer tools.

For lightweight comparisons between requests or responses, a JSON or text diff tool can expose a changed field that is difficult to notice visually. The guide to online diff tools covers that workflow.

When to revisit

Keep this checklist close whenever an API contract, authentication flow, frontend environment, or testing tool changes. Revisit it before a seasonal planning or release cycle if the request supports scheduled jobs, reporting, imports, or other workflows that may run less frequently than normal development tasks. It is also worth updating after an API version change, a migration from cookies to tokens, a change in browser behavior, or a replacement of your API testing client.

Turn the workflow into a short team runbook. Include the approved test endpoint, a safe sample payload, the command used to reproduce the request, the expected status code, and instructions for redacting credentials. Review the examples when the API schema changes so that the runbook remains useful rather than becoming another source of confusion.

Before closing an incident, run this final sequence:

1. Reproduce the issue with a minimal request.
2. Identify the first layer that differs from a known working request.
3. Correct one variable and repeat the test.
4. Confirm the fix in the original application context.
5. Record the cause, evidence, and prevention step without retaining secrets.

This process makes API request debugging more predictable. Instead of treating JSON formatters, JWT decoders, browser tools, and API clients as disconnected utilities, use them as checkpoints in one repeatable diagnostic workflow.