Error Model

Errors use a stable JSON envelope: error.type, error.code, error.message, request_id, optional doc_url, and optional details. GET /v1/errors returns the first-class error catalog with code, HTTP status, type, retry posture, and documentation link. Authentication failures return 401 invalid_auth or access-token specific errors. Changed idempotent replays return 409 conflicts. Validation blockers return structured details so client UIs can show actionable corrections.

{
  "error": {
    "type": "api_error",
    "code": "idempotency_key_conflict",
    "message": "This idempotency key was already used with a different payload.",
    "request_id": "req_...",
    "doc_url": "https://docs.helvcore.ch/v1/errors/"
  }
}