Errors

Every failure uses the same envelope:

{
  "error": {
    "type": "validation_error",
    "code": "invalid_request",
    "message": "The request could not be accepted.",
    "details": [{ "pointer": "/parts/0/body", "message": "is required" }]
  },
  "request_id": "req_…"
}

error.type is the broad class and error.code is the specific failure. Both sets grow additively: branch on values you handle and treat unknown values as a generic failure. Do not model either as a closed enum.

error.details identifies field failures with JSON Pointers. error.context may carry typed facts needed to decide a remedy. Neither field is guaranteed on every error.

Log the HTTP status, request_id, type, and code. Never log credentials or message content. A 429 may include Retry-After; honor it when present.