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

ware 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.

```typescript
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.

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

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.