Validation Errors

Validation errors are the most common errors an API returns, and the ones clients most want to render nicely. A good validation response tells the user exactly which fields are wrong and why — all of them at once, not one per round trip.

Status: 422 (or 400)

When the request parsed correctly but the values fail your rules, return 422 Unprocessable Entity. Some teams use 400 for all client errors; either is defensible, but be consistent. Reserve 400 for requests you could not even parse.

A field-level error body

Extend Problem Details with an errors array, one entry per offending field:

{
  "type": "https://api.example.com/problems/validation",
  "title": "Validation failed",
  "status": 422,
  "detail": "The request has 2 invalid fields.",
  "errors": [
    { "field": "email", "message": "must be a valid email address" },
    { "field": "age", "message": "must be 18 or greater" }
  ]
}

Collect all errors, then respond

Validate every field and gather all failures before responding — do not bail on the first. This mirrors how a typical schema validator works:

JavaScript

function validateUser(input) {
  const errors = [];
  if (typeof input.email !== 'string' || !input.email.includes('@')) {
    errors.push({ field: 'email', message: 'must be a valid email address' });
  }
  if (typeof input.age !== 'number' || input.age < 18) {
    errors.push({ field: 'age', message: 'must be 18 or greater' });
  }
  return errors;
}

const errors = validateUser({ email: 'nope', age: 16 });
if (errors.length > 0) {
  const body = {
    type: 'https://api.example.com/problems/validation',
    title: 'Validation failed',
    status: 422,
    detail: 'The request has ' + errors.length + ' invalid fields.',
    errors,
  };
  console.log(JSON.stringify(body, null, 2));
}

In TypeScript projects a schema library (such as zod) gives you this for free: parse the input against a schema, and on failure map the issues to your errors array.