JSON Error Handling Best Practices

Why JSON Error Handling Matters

JSON errors are among the most common runtime failures in web applications. An API returns HTML instead of JSON, a user pastes malformed input, or a network error truncates a response — any of these crashes an app that does not handle errors properly.

Safe JSON.parse in JavaScript

// Never do this — crashes on invalid input
const data = JSON.parse(userInput);

// Always do this
function safeParseJSON(str, fallback = null) {
  try {
    return JSON.parse(str);
  } catch (e) {
    console.error('JSON parse failed:', e.message);
    return fallback;
  }
}

const data = safeParseJSON(userInput, {});

Handling API JSON Errors

async function fetchJSON(url) {
  const res = await fetch(url);

  // Check HTTP status before parsing
  if (!res.ok) {
    throw new Error(`HTTP ${res.status}: ${res.statusText}`);
  }

  // Check Content-Type — API might return HTML on error
  const contentType = res.headers.get('content-type');
  if (!contentType?.includes('application/json')) {
    const text = await res.text();
    throw new Error(`Expected JSON, got ${contentType}: ${text.slice(0, 200)}`);
  }

  return res.json();
}

// Usage
try {
  const data = await fetchJSON('/api/users');
} catch (e) {
  console.error('Failed to fetch:', e.message);
}

TypeScript: Type-Safe JSON Parsing

import { z } from 'zod';

const UserSchema = z.object({
  id: z.number(),
  name: z.string(),
  email: z.string().email()
});

type User = z.infer<typeof UserSchema>;

async function getUser(id: number): Promise<User> {
  const res = await fetch(`/api/users/${id}`);
  const raw = await res.json();
  return UserSchema.parse(raw); // throws ZodError if invalid
}

Python Error Handling

import json
from typing import Any, Optional

def safe_parse(text: str, fallback: Any = None) -> Any:
    try:
        return json.loads(text)
    except json.JSONDecodeError as e:
        print(f'JSON error at line {e.lineno}, col {e.colno}: {e.msg}')
        return fallback

# Requests library
import requests

def fetch_json(url: str) -> Optional[dict]:
    try:
        res = requests.get(url, timeout=10)
        res.raise_for_status()  # Raises for 4xx/5xx
        return res.json()
    except requests.exceptions.JSONDecodeError:
        print('Response is not valid JSON')
    except requests.exceptions.HTTPError as e:
        print(f'HTTP error: {e}')
    except requests.exceptions.RequestException as e:
        print(f'Network error: {e}')
    return None

Common Error Patterns

FAQ