Consistent error envelope

{
  "error": {
    "code":       "VALIDATION_FAILED",
    "message":    "The request body failed validation.",
    "request_id": "req_01hx9k3p2m",
    "details": [
      { "field": "email", "issue": "Must be a valid email address" },
      { "field": "amount", "issue": "Must be greater than 0" }
    ]
  }
}

Every error response uses the same envelope. Clients parse one shape, not a different shape per endpoint.

HTTP status codes

  • 400 — client sent invalid input.
  • 401 — not authenticated.
  • 403 — authenticated but not authorised.
  • 404 — resource does not exist.
  • 409 — conflict (duplicate, version mismatch).
  • 422 — input is syntactically valid but semantically wrong.
  • 429 — rate limited.
  • 500 — server error (never expose stack traces).

Machine-readable codes

The code field is a stable string constant. Use it in client switch statements — never match on the human-readable message, which may change.