5 Common JSON Errors That Break APIs (and How to Fix Them)

me safety.

Architecture Decisions

1. Schema as Source of Truth: Define the payload structure once. The schema generates TypeScript types, eliminating duplication and ensuring compile-time and runtime consistency.
2. Middleware Validation: Intercept requests at the edge or controller level. Validate before the payload reaches business logic. This implements a fail-fast pattern.
3. Strict Typing: Disable type coercion by default. If a field is defined as a boolean, reject string representations. This prevents subtle logic errors.
4. Error Normalization: Convert validation errors into a standardized error response format. This aids client debugging and monitoring.

Implementation Steps

Step 1: Define the Schema

Create a schema that enforces strict types and required fields. This catches unquoted keys (parser error), missing commas (parser error), and type mismatches (schema error).

import { z } from 'zod';

// Define strict schema for user configuration payload
const UserConfigSchema = z.object({
  // Enforces string type; rejects numbers or booleans
  userId: z.string().uuid(),
  
  // Strict boolean; rejects "true", "false", 1, 0
  isActive: z.boolean(),
  
  // Numeric type; rejects "100" or "10.5"
  maxRetries: z.number().int().min(0).max(10),
  
  // Array of strings; rejects array of mixed types
  permissions: z.array(z.string()).nonempty(),
  
  // Optional field with default
  theme: z.enum(['light', 'dark']).default('light'),
});

// Infer TypeScript type automatically
export type UserConfig = z.infer<typeof UserConfigSchema>;

Step 2: Create Validation Middleware

Build a middleware function that parses the request body against the schema. If validation fails, it throws a structured error.

import { Request, Response, NextFunction } from 'express';
import { ZodError } from 'zod';

// Generic validation middleware factory
export const validatePayload = (schema: z.ZodTypeAny) => {
  return (req: Request, res: Response, next: NextFunction) => {
    try {
      // Parse and validate; throws ZodError on failure
      const validatedData = schema.parse(req.body);
      
      // Attach validated data to request object
      // This ensures downstream code only sees safe data
      req.validatedBody = validatedData;
      next();
    } catch (error) {
      if (error instanceof ZodError) {
        // Return 400 with detailed validation issues
        res.status(400).json({
          error: 'Validation Failed',
          details: error.errors.map(err => ({
            path: err.path.join('.'),
            message: err.message,
          })),
        });
      } else {
        // Handle unexpected errors (e.g., JSON parse failure)
        res.status(400).json({
          error: 'Malformed JSON',
          message: 'The request body is not valid JSON.',
        });
      }
    }
  };
};

Step 3: Apply to Routes

Integrate the middleware into your API routes.

import express from 'express';

const app = express();
app.use(express.json());

app.post(
  '/api/v1/users/config',
  validatePayload(UserConfigSchema),
  (req: Request, res: Response) => {
    // req.validatedBody is now type-safe UserConfig
    const config = req.validatedBody as UserConfig;
    
    // Business logic proceeds with guaranteed data integrity
    res.json({ status: 'success', config });
  }
);

Rationale:

• Zod over JSON Schema: Zod offers superior TypeScript integration, allowing types to be inferred directly from the schema. This reduces maintenance overhead.
• Strict Parsing: The middleware catches JSON syntax errors (like trailing commas or missing braces) via the express.json() parser before Zod runs, providing a two-layer defense.
• Type Safety: By attaching validatedBody, the application eliminates the need for manual type checks or assertions in business logic.

Pitfall Guide

Even with robust tooling, specific failure modes persist. The following pitfalls are derived from production experience and highlight common mistakes with actionable fixes.

Pitfall Name	Explanation	Fix
The Stringified Boolean Trap	Clients send "isActive": "true" instead of true. Syntax is valid, but logic breaks when checking if (isActive).	Use strict boolean schemas. Reject string inputs. Educate clients on type requirements.
Trailing Comma in Source	Developers copy-paste JSON from JavaScript objects, leaving trailing commas. JSON parsers reject this immediately.	Use linters in CI/CD. Configure editors to warn on trailing commas. Never hand-edit JSON in production configs.
Unquoted Keys from Legacy	Legacy systems or manual edits produce {name: "value"}. This violates RFC 8259 and causes parse failures.	Implement a pre-processing step for legacy integrations, or enforce strict rejection with clear error messages.
Missing Delimiters	Manual edits omit commas between fields, e.g., {"a": 1 "b": 2}. Results in syntax errors.	Automate payload generation. Use schema validation in CI pipelines to catch config errors before deployment.
Structural Mismatch	Arrays contain objects when strings are expected, or required fields are missing.	Define comprehensive schemas with required fields and strict array item types. Use nonempty() constraints where applicable.
Numeric ID Coercion	IDs sent as numbers instead of strings can lose precision for large integers (exceeding Number.MAX_SAFE_INTEGER).	Define ID fields as strings in schemas. Validate format (e.g., UUID) rather than relying on numeric types.
Silent Validation Failures	Catching validation errors and returning 200 OK with an error field. Clients may miss the failure.	Always return 4xx status codes for validation errors. Ensure error responses are distinct from success payloads.

Best Practices:

• Schema-First Design: Write schemas before implementation. This serves as documentation and contract for both client and server.
• Automate Validation: Run schema checks in CI/CD pipelines for configuration files and mock responses.
• Monitor Validation Errors: Track 400 errors caused by validation failures. Spikes may indicate client bugs or API contract changes.
• Version Contracts: When schemas evolve, version your API or use backward-compatible changes to avoid breaking existing clients.

Production Bundle

Action Checklist

• Define Schemas: Create Zod or JSON Schema definitions for all public API endpoints.
• Implement Middleware: Add validation middleware to intercept and verify all incoming payloads.
• Enforce Strict Types: Disable type coercion in schemas; require exact type matches.
• CI/CD Integration: Add JSON linting and schema validation steps to the build pipeline.
• Error Standardization: Ensure validation errors return consistent 400 responses with detailed paths.
• Type Inference: Use schema inference to generate TypeScript types, eliminating manual type definitions.
• Chaos Testing: Test endpoints with malformed payloads (trailing commas, wrong types, missing fields) to verify error handling.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
Internal Microservices	Zod Runtime Validation	Fast, type-safe, low overhead, integrates with TS ecosystem.	Low
Public API Gateway	JSON Schema + WAF	Language-agnostic, standard compliance, supports complex constraints.	Medium
Legacy Integration	Pre-processor + Strict Schema	Handles dirty data from old systems while enforcing modern contracts.	High
Configuration Files	JSON Schema + CI Linting	Catches syntax errors early; ensures config validity before deployment.	Low

Configuration Template

Use this template to bootstrap schema validation in a TypeScript project.

// schemas/api-payload.ts
import { z } from 'zod';

export const ApiPayloadSchema = z.object({
  id: z.string().uuid(),
  timestamp: z.string().datetime(),
  data: z.record(z.unknown()),
  metadata: z.object({
    source: z.string(),
    version: z.string().regex(/^\d+\.\d+\.\d+$/),
  }).optional(),
});

export type ApiPayload = z.infer<typeof ApiPayloadSchema>;

// middleware/validate.ts
import { Request, Response, NextFunction } from 'express';
import { ZodSchema, ZodError } from 'zod';

export const validate = (schema: ZodSchema) => (req: Request, res: Response, next: NextFunction) => {
  try {
    req.validatedBody = schema.parse(req.body);
    next();
  } catch (err) {
    if (err instanceof ZodError) {
      return res.status(400).json({
        error: 'VALIDATION_ERROR',
        issues: err.errors.map(e => ({ path: e.path, message: e.message })),
      });
    }
    return res.status(400).json({ error: 'PARSE_ERROR', message: 'Invalid JSON structure.' });
  }
};

Quick Start Guide

1. Install Dependencies: Run npm install zod and npm install -D @types/zod if needed.
2. Create Schema File: Define your payload structure using Zod primitives and constraints.
3. Add Middleware: Import the validation middleware and apply it to your route handlers.
4. Test Locally: Use curl or Postman to send valid and invalid payloads. Verify that invalid payloads return 400 with detailed error messages.
5. Deploy: Commit schema definitions and middleware. Ensure CI/CD pipelines include validation checks for configuration files.