JSON API Debugging Checklist: Fast Root Cause Isolation

When an API integration fails, the error message is often vague: "invalid request", "bad payload", or "signature mismatch". A short, repeatable checklist helps you identify the real cause quickly.

Step 1: Validate Raw JSON First

Paste the exact payload into JSON ↔ YAML Converter before anything else.

Look for:

• Trailing commas
• Wrong quote type (single vs double)
• Missing commas between fields
• Unexpected nested structures

Step 2: Verify Encoding Boundaries

Three frequent issues:

1. Base64 value is decoded with the wrong variant.
2. URL parameters are encoded twice.
3. UTF-8 text is treated as a different charset.

Use:

• URL Encode/Decode
• JWT Decoder for Base64URL token payloads

Step 3: Confirm Time Fields

Timestamp mismatches are easy to miss:

• Seconds vs milliseconds
• UTC vs local timezone
• Expired token timestamps

Write down the raw number and confirm which unit your API expects before comparing it with logs or token claims.

Step 4: Inspect Token Claims

For auth-related failures, decode JWT claims with JWT Decoder and verify:

• exp has not expired
• aud matches your API audience
• iss and sub are correct

Step 5: Compare Expected vs Actual

If a request "looks fine" but still fails, compare two payloads side by side:

• One known-good request from logs
• One failing request

Even small differences (field name casing, null vs empty string, order-sensitive signature input) become obvious when formatted.

Team Habit That Saves Time

Keep a short "pre-flight check" in your PR template:

1. JSON validated
2. Encoding verified
3. Timestamp interpretation confirmed
4. Token claims checked
5. Example request/response attached

This turns repeated production incidents into a predictable verification process.