Errors and Validation

Use one error format everywhere — RFC 9457 Problem Details (type, title, status, detail, instance) plus extensions like field errors and a request ID. Validate input at the boundary and return all field errors at once. Distinguish client errors (4xx, fixable by the caller) from server errors (5xx), and never leak stack traces or SQL.

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json

{
  "type": "https://api.example.com/problems/validation",
  "title": "Your request is invalid",
  "status": 422,
  "errors": [
    {"field": "items[0].qty", "message": "must be at least 1"},
    {"field": "currency", "message": "must be a 3-letter ISO code"}
  ],
  "request_id": "req_7f3a9c"
}

Common pitfalls

• Different error shapes per endpoint.
• Only returning the first validation error.
• 500 for client mistakes (or 400 for server bugs).

Key points

• Problem Details everywhere
• All field errors at once
• Request IDs for support

Further reading: RFC 9457: Problem Details