API Debugging Checklist: Format JSON, Decode JWTs, and Test Requests Safely

Overview

Effective API debugging is less about trying random fixes and more about isolating one variable at a time. Start with the request as the client sends it, then compare it with the API contract, server response, and relevant application logs. A structured workflow is especially useful in cloud-native systems, where a request may pass through a browser, gateway, load balancer, service, cache, or worker before it reaches its destination.

Keep these four questions in view:

• What was sent? Check the method, URL, query parameters, headers, and body.
• What was received? Read the status code, response headers, body, and timing.
• Where did the request change? Look for encoding, proxy, redirect, parsing, or authentication differences.
• Can the result be reproduced safely? Record a sanitized request and a clear expected result.

An online developer tool can speed up inspection, but convenience should not override data handling. Remove production credentials, personal information, private keys, session cookies, and proprietary payloads before using a browser-based formatter, decoder, or tester. For additional guidance, see how to safely use online encoding and decoding tools with sensitive data.

Checklist by scenario

When a request returns a client error

1. Confirm the HTTP method. A server may treat POST, PUT, and PATCH differently even when they use similar paths.
2. Copy the complete request URL and check its path, query parameters, spelling, and trailing slash.
3. Inspect the Content-Type header. A JSON body normally needs a JSON media type that matches the server’s expectations.
4. Paste the body into a JSON formatter or JSON beautifier and validator. Look for missing commas, unmatched braces, invalid quotation marks, duplicate keys, and incorrect value types.
5. Compare field names and required fields with the API contract. Pay particular attention to case, nesting, arrays, null values, and numeric-versus-string values.
6. Remove optional fields one at a time if the server rejects the payload. This helps identify whether a particular field or format causes validation to fail.

A formatter improves readability, but valid JSON is not necessarily valid application data. A syntactically correct payload can still fail because a field is missing, too long, outside an allowed range, or in the wrong business state.

When authentication or authorization fails

1. Confirm that the expected authentication scheme is present and correctly formatted in the request headers.
2. Check whether the token is missing, expired, intended for another environment, or associated with insufficient permissions.
3. Use a JWT decoder only on a redacted or non-sensitive token when possible. Inspect the header and payload for claims such as issuer, audience, subject, scope, and expiration.
4. Remember that decoding is not verification. A token decoder displays encoded contents; it does not prove that the signature is valid or that the token should be trusted.
5. Compare the token’s time claims with the server’s clock and expected time zone. A timestamp converter can help when Unix timestamps and ISO 8601 values are being compared.
6. Check whether a gateway validates the token before the application receives the request. Different layers may produce different error messages.

Never paste private keys, refresh tokens, session cookies, or active production credentials into an unapproved third-party tool. For background on token formats, see PEM, JWT, and Base64: a practical guide.

When query parameters or paths behave unexpectedly

1. Separate the base URL, path, query string, and fragment. Fragments are handled by clients and are generally not sent to a server.
2. Check reserved characters such as spaces, ampersands, question marks, slashes, plus signs, and percent symbols.
3. Use a URL encoder for individual parameter values, not automatically for an entire URL. Encoding the wrong component can change its structure.
4. Test whether the client and server interpret spaces, plus signs, Unicode characters, and repeated parameters in the same way.
5. Inspect redirects and proxy rewrites. The request that arrives at the application may not match the URL shown in the original client.

When the response looks correct but the app still fails

1. Compare the response body with the frontend or service’s actual parsing logic.
2. Check response headers, especially content type, caching directives, compression, and cross-origin behavior.
3. Look for a shape mismatch: an object where an array is expected, a renamed property, a null value, or a number represented as text.
4. Use a text diff checker to compare a working payload with a failing one after removing secrets and volatile identifiers.
5. Confirm that the client is calling the environment you intended. Development, staging, and production may expose similar paths with different schemas or credentials.

What to double-check

Before changing code, capture a small, sanitized record of the failure:

• Request method and endpoint, excluding secrets in query strings.
• Relevant headers, with authorization and cookies removed or masked.
• Validated request body and the expected schema.
• Response status, headers, body, and a correlation or request ID if available.
• Timestamp, environment, client version, and whether the issue is consistent or intermittent.

Use status codes as clues rather than complete explanations. A 4xx response commonly points to the request, identity, permissions, or resource state, while a 5xx response commonly indicates a server-side or upstream problem. Gateways and proxies can also generate responses, so identify which layer produced the status before assigning ownership.

For configuration-related failures, compare the actual deployed values with the intended values rather than relying only on a local file. If the configuration format is part of the problem, the guide to YAML versus JSON for config files provides useful validation considerations.

Common mistakes

• Debugging the body before checking the method: A perfectly formatted payload still fails when sent to the wrong operation.
• Treating decoded JWT claims as proof: Readable claims do not establish signature validity, issuer trust, or permission.
• Encoding an entire URL: Encode the value that needs protection from reserved-character interpretation, then assemble the URL correctly.
• Copying secrets into logs: Redact authorization headers, cookies, tokens, passwords, and personal data before sharing traces.
• Assuming a 200 response means success: Inspect the response body and application-level error fields as well as the HTTP status.
• Changing several variables at once: Alter one header, field, or environment setting, then repeat the request so the result is meaningful.
• Ignoring time: Expiration claims, signed URLs, caches, scheduled jobs, and distributed services can all behave differently when clocks or time zones are misunderstood.

When a browser is part of the workflow, use its network panel to compare the intended request with the request actually sent. A practical browser-based debugging process can complement command-line clients and automated tests.

When to revisit

Keep this checklist with the team’s API runbooks and revisit it whenever the underlying inputs change. That includes a new authentication provider, gateway rule, API version, frontend client, serialization library, proxy, or deployment environment. It is also useful before seasonal planning cycles, when teams may update scheduled jobs, rotate credentials, revise traffic controls, or change configuration between environments.

Review the tools in your workflow when their handling of sensitive data, supported formats, or team approval requirements changes. A lightweight local JSON formatter, URL encoder, JWT inspection method, or request test script may be preferable for confidential material. Online tools are most appropriate for sanitized examples and non-sensitive debugging tasks.

Print or save this short version for the next incident:

1. Reproduce the request and record the exact method, URL, headers, body, and response.
2. Remove secrets and personal data from every copied example.
3. Validate and format the JSON payload.
4. Check URL encoding, content type, field types, and required values.
5. Decode tokens only for inspection; verify them through the appropriate trusted mechanism.
6. Use the status code, response body, request ID, and logs to locate the failing layer.
7. Change one variable, retest, and document the result.

This sequence turns a vague API failure into a series of testable questions and creates a reusable record for future debugging.