How to Debug APIs Using JSON Formatting Tools

Meta Description: Learn to debug REST APIs faster with JSON formatting and validation tools. Practical techniques for reading responses, finding errors, and fixing common API issues.

You fire off an API request and get back a wall of minified JSON. One massive line, no indentation, thousands of characters. Somewhere in that blob is the data you need — or the error that's breaking your app. Good luck finding it.

This is why JSON formatting tools exist. They turn unreadable API responses into structured, scannable data. But formatting is just the starting point. Knowing how to read and debug JSON responses is a skill that saves hours of frustration.

Why APIs Return Minified JSON

Most APIs return minified (compact) JSON — no whitespace, no newlines, everything on one line:

{"status":"error","code":422,"errors":[{"field":"email","message":"already exists"},{"field":"password","message":"must be at least 8 characters"}],"meta":{"requestId":"req_abc123","timestamp":"2025-01-15T10:30:00Z"}}

This is intentional. Whitespace adds bytes. For an API serving millions of requests, pretty-printing every response wastes bandwidth and processing time. The savings are real: a typical API response is 20-30% smaller when minified.

Your browser's network tab, curl output, and log files all show this minified format. Your first debugging step is almost always: format the JSON.

Step 1: Format the Response

Take that wall of text and make it readable. You have several options:

Online Formatter (Fastest)

Paste your JSON into our JSON formatter and get instant pretty-printed output with:

• Proper indentation
• Syntax highlighting
• Error detection with line numbers
• Collapsible sections for nested objects

This is the fastest path from "what is this mess?" to "oh, there's the problem."

Command Line

# Using jq (recommended — install with brew/apt)
curl -s https://api.example.com/users | jq .

# Using Python
curl -s https://api.example.com/users | python -m json.tool

# Using Node.js
curl -s https://api.example.com/users | node -e "process.stdin.pipe(require('stream').Transform({transform(c,e,cb){cb(null,JSON.stringify(JSON.parse(c),null,2))}}))" 

# Simplest with jq
echo '{"compact":"json"}' | jq .

jq is the Swiss Army knife of JSON on the command line. It formats, filters, transforms, and queries JSON. If you don't have it installed, stop reading and install it now.

Browser DevTools

Chrome and Firefox automatically format JSON responses in the Network tab. Click on a request, go to the Preview or Response tab, and you get formatted JSON with expandable/collapsible nodes.

Pro tip: Install a JSON viewer browser extension. When you navigate directly to an API endpoint, the extension formats the response automatically instead of showing raw text.

IDE/Editor

VS Code: Select JSON text → Shift+Alt+F (or Shift+Option+F on Mac) to format. You can also install extensions like "Prettier" that format on save.

Step 2: Understand the Response Structure

Now that you can read the JSON, look at the structure. Most well-designed APIs follow consistent patterns:

Success Response

{
  "status": "success",
  "data": {
    "user": {
      "id": 42,
      "name": "Alice Chen",
      "email": "[email protected]",
      "createdAt": "2025-01-15T10:30:00Z"
    }
  },
  "meta": {
    "requestId": "req_abc123"
  }
}

The actual data is usually nested under a data key. Metadata (pagination, request IDs, rate limits) lives in meta or at the top level.

Error Response

{
  "status": "error",
  "code": 422,
  "message": "Validation failed",
  "errors": [
    {
      "field": "email",
      "code": "DUPLICATE",
      "message": "A user with this email already exists"
    },
    {
      "field": "password",
      "code": "TOO_SHORT",
      "message": "Password must be at least 8 characters"
    }
  ],
  "meta": {
    "requestId": "req_def456",
    "documentation": "https://api.example.com/docs/errors/422"
  }
}

Error responses tell you what went wrong and (in good APIs) how to fix it. The errors array pinpoints specific fields and issues.

Paginated Response

{
  "data": [
    {"id": 1, "name": "Item 1"},
    {"id": 2, "name": "Item 2"}
  ],
  "pagination": {
    "total": 150,
    "page": 1,
    "perPage": 20,
    "totalPages": 8,
    "nextCursor": "eyJpZCI6MjB9"
  }
}

Check the pagination object to understand if you're getting all the data or just a page.

Step 3: Extract What You Need

Once formatted, use jq to drill into specific parts:

# Get just the user's name
curl -s api.example.com/users/42 | jq '.data.user.name'

# Get all error messages
curl -s api.example.com/register | jq '.errors[].message'

# Get the first item in a list
curl -s api.example.com/items | jq '.data[0]'

# Count results
curl -s api.example.com/items | jq '.data | length'

# Filter by condition
curl -s api.example.com/users | jq '.data[] | select(.active == true)'

# Get specific fields from all items
curl -s api.example.com/users | jq '.data[] | {name, email}'

jq is ridiculously powerful. Learning its basics — dot notation, array indexing, select(), and pipe | — will speed up your API debugging dramatically.

Common API Debugging Scenarios

Scenario 1: Unexpected Empty Response

Symptom: {"data": []} or {"data": null}

Debug steps:

1. Check your query parameters — are you filtering too aggressively?
2. Check pagination — are you requesting page 0 instead of page 1?
3. Check authentication — some APIs return empty data instead of 403 for unauthorized requests
4. Check the endpoint URL — typos in resource names often return empty results instead of 404

# Compare with and without filters
curl -s "api.example.com/users" | jq '.data | length'
curl -s "api.example.com/users?status=active" | jq '.data | length'

Scenario 2: 400 Bad Request with Unhelpful Message

Symptom: {"error": "Bad Request"}

Debug steps:

1. Format and examine the full response — there might be more detail you're missing
2. Check your request body is valid JSON (use our formatter to validate)
3. Check Content-Type header is application/json
4. Check for required fields you might be missing

# Verbose curl to see request and response headers
curl -v -X POST api.example.com/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice"}' 2>&1 | head -50

Scenario 3: Data Type Mismatches

Symptom: Your app crashes parsing the response, or values are wrong.

Debug steps:

1. Format the response and check data types carefully
2. Look for strings where you expect numbers: "id": "42" vs "id": 42
3. Look for null where you expect values: "name": null
4. Check date formats — is it ISO 8601 or Unix timestamp?

# Check types with jq
curl -s api.example.com/users/42 | jq '.data.user | to_entries[] | {key, type: (.value | type)}'

Scenario 4: Nested Data You Can't Access

Symptom: The data is there when you format it, but your code can't access it.

Debug steps:

1. Map out the nesting levels — the data might be deeper than you think
2. Check for arrays that wrap single objects: "user": [{"name": "Alice"}] requires user[0].name, not user.name
3. Check for inconsistent response shapes between endpoints

# Visualize the structure (keys only, 2 levels deep)
curl -s api.example.com/complex | jq 'path(..) | join(".")'

Scenario 5: Rate Limiting

Symptom: {"error": "Too Many Requests"} (HTTP 429)

Debug steps:

1. Check response headers for rate limit info
2. Most APIs include X-RateLimit-Remaining and X-RateLimit-Reset headers
3. Implement exponential backoff in your code

# Check rate limit headers
curl -sI api.example.com/users | grep -i rate

Building a Debugging Workflow

Here's the workflow I recommend for any API issue:

1. Reproduce the request with curl (isolate from your app code)
2. Format the response (paste into our formatter or pipe through jq)
3. Read the full response — including headers, not just the body
4. Compare with the API documentation
5. Isolate — strip your request down to the minimum, then add back complexity
6. Log the request ID for support tickets

Essential curl Flags

# See headers + body
curl -v URL

# POST with JSON body
curl -X POST URL -H "Content-Type: application/json" -d '{"key":"value"}'

# Include response headers in output
curl -i URL

# Save response to file for analysis
curl -s URL -o response.json

# Time the request
curl -w "\nTime: %{time_total}s\n" -s URL

# Follow redirects
curl -L URL

JSON Validation in Your Code

Don't just format during debugging — validate in production too:

// JavaScript — safe parsing
function parseJSON(text) {
  try {
    return { data: JSON.parse(text), error: null };
  } catch (e) {
    return { data: null, error: e.message };
  }
}

# Python — safe parsing
import json

def parse_json(text):
    try:
        return json.loads(text), None
    except json.JSONDecodeError as e:
        return None, f"Invalid JSON at line {e.lineno}, col {e.colno}: {e.msg}"

The Bottom Line

API debugging is 80% "can I read this response?" and 20% actual logic problems. Get a good JSON formatter in your toolkit — whether it's our web tool, jq on the command line, or a browser extension — and you'll solve most API issues in minutes instead of hours.

Format first. Read the structure. Extract what you need. Fix the problem.

FAQ

What's the best JSON formatter for large files?

For files over 10MB, command-line tools like jq outperform browser-based formatters. jq streams data efficiently and can handle files of any size. For browser-based formatting of moderate files (up to ~5MB), our tool works smoothly with syntax highlighting.

How do I format JSON in curl output automatically?

Pipe through jq: curl -s api.example.com/endpoint | jq . — this formats, colorizes, and validates in one step. Alternatively, many HTTP clients (Postman, Insomnia, HTTPie) format responses automatically.

Why does my valid JSON fail to parse?

Common culprits: BOM (Byte Order Mark) at the start of the file, trailing commas (valid in JavaScript but not JSON), single quotes instead of double quotes, or unescaped control characters in strings. Run it through a strict validator to get the exact error.

Can I compare two JSON responses to find differences?

Yes. Use diff <(jq -S . file1.json) <(jq -S . file2.json) on the command line. The -S flag sorts keys, so differences show actual data changes, not just reordering. Online diff tools also work for quick comparisons.

How do I handle JSON responses with special characters?

Ensure your HTTP client is using UTF-8 encoding (check the Content-Type header for charset=utf-8). JSON is UTF-8 by default. If you see garbled characters, the issue is usually encoding mismatch between the API and your client.