Format an API Error Response

Well-designed API error responses are what separates APIs that developers love from ones they hate. When an error response is structured consistently and contains enough information to understand what went wrong and how to fix it, client developers can write robust error-handling code. When errors are minified, inconsistently structured, or contain only a generic message, debugging integrations becomes a frustrating guessing game. This example follows the RFC 7807 Problem Details for HTTP APIs standard — a widely adopted specification that many modern REST APIs use. The format defines a predictable envelope: type is a URI identifying the error category (linking to documentation), title is a human-readable summary, status mirrors the HTTP status code, detail provides a more specific description, and instance identifies the specific request that caused the error. The errors array is a common extension to the base spec for listing field-level validation failures. Key parts explained: HTTP 422 Unprocessable Entity indicates the request was syntactically valid but failed semantic or business validation — the server understood what you were asking for but couldn't process it. The errors array gives the client exactly which fields failed and why, enabling the UI to highlight specific form fields with inline error messages rather than showing a generic "something went wrong" banner. Real-world scenarios: a mobile app registration form that highlights the email field red when the API returns {"field": "email", "message": "Must be a valid email address"} provides a far better user experience than one that shows an alert dialog. An automated integration that can programmatically distinguish 422 validation errors from 500 server errors can implement different retry strategies for each. Tips for API designers: use the type field as a machine-readable identifier that client code can switch on. Use detail for human-readable information that might be shown to the user. Keep error messages consistent — if the same validation failure can be triggered by different code paths, ensure they all return the same message so clients can test against it reliably. To use this example: format your own API error responses here to verify they follow a consistent structure before documenting them or sharing them with client developers.

{
  "type": "https://example.com/problems/validation-error",
  "title": "Validation Failed",
  "status": 422,
  "detail": "One or more fields failed validation.",
  "instance": "/api/users",
  "errors": [
    { "field": "email", "message": "Must be a valid email address." },
    { "field": "password", "message": "Must be at least 8 characters." }
  ]
}