API Standardized Error Handling

Standardized Error Handling (RFC 9457)

Use this skill when defining or reviewing API error responses. Prefer application/problem+json over ad-hoc { "status": "error", "msg": "..." }.

1. Problem Details core fields

2. Validation errors

Return all field errors in one response. Extend with an errors map:

{
  "type": "https://api.example.com/errors/validation",
  "title": "Validation failed",
  "status": 422,
  "detail": "One or more fields are invalid",
  "errors": {
    "email": ["must be a valid email"],
    "qty": ["must be >= 1"]
  }
}

Domain codes belong in type (preferred) or a documented code extension — keep the HTTP status correct for the transport class.

3. Status pairing

Never return 200 with an error object. Omit stack traces, internal IDs, and secrets in production.

4. Consistency

Use the same error envelope across all active API versions. Catalogue every type in OpenAPI / docs. Treat the error shape as a contract.

5. Quick checklist

• Default Content-Type: application/problem+json.
• type, title, status, detail present.
• Multi-field errors on validation failures.
• HTTP status matches problem class.
• No secrets/stack traces in production.
• Types documented; shape stable across versions.

See reference.md and examples.md.