{
  "schema": "tiffany.systems/schema/error-taxonomy/1.0.0",
  "note": "The public error taxonomy for errors returned by implemented Tiffany API endpoints. See scope: requests to unknown paths are handled by the hosting layer and are not governed by this contract.",
  "scope": {
    "statement": "Tiffany's JSON error contract governs errors returned by implemented Tiffany API endpoints. A request to an unknown or nonexistent path never reaches one: it is handled by the hosting layer and may return the host's native 404 response rather than Tiffany's JSON error envelope.",
    "why": "Every endpoint here is a static document. It either exists, in which case it is returned, or it does not, in which case the request is resolved by the host before any Tiffany code would run. Unknown-path handling is therefore outside this contract rather than an unimplemented part of it.",
    "client_rule": "Treat any non-200 as an error and do not assume the body is JSON. Parse an error envelope only when an implemented endpoint returned it.",
    "today": "No implemented endpoint currently emits an error envelope, because a static document cannot fail in a way that produces one. The taxonomy is fixed in advance so its shape cannot be invented differently under pressure when the first endpoint that can fail is built."
  },
  "error_schema": "/api/schema/error.schema.json",
  "documentation": "https://tiffany.systems/developers/api/errors",
  "codes": [
    {
      "code": "not_found",
      "http": 404,
      "retryable": false,
      "meaning": "The endpoint exists but the object it was asked for does not.",
      "emitted_by_implemented_endpoint": false,
      "note": "Not to be confused with a request to an unknown path, which never reaches a Tiffany endpoint and is answered by the hosting layer — see error_contract_scope."
    },
    {
      "code": "invalid_request",
      "http": 400,
      "retryable": false,
      "meaning": "The request was malformed.",
      "emitted_by_implemented_endpoint": false
    },
    {
      "code": "validation_failed",
      "http": 422,
      "retryable": false,
      "meaning": "The request was well formed but an input failed validation. Names the offending field.",
      "emitted_by_implemented_endpoint": false
    },
    {
      "code": "unsupported_version",
      "http": 400,
      "retryable": false,
      "meaning": "The requested API contract version is not served.",
      "emitted_by_implemented_endpoint": false
    },
    {
      "code": "withdrawn_object",
      "http": 200,
      "retryable": false,
      "meaning": "Not an error condition on this surface. A withdrawn record returns 200 with its original bytes and lifecycle WITHDRAWN; the code exists for future endpoints that must refuse an operation on a withdrawn object.",
      "emitted_by_implemented_endpoint": false
    },
    {
      "code": "superseded_object",
      "http": 200,
      "retryable": false,
      "meaning": "As above. A superseded version is still served, still citable, and carries superseded_by.",
      "emitted_by_implemented_endpoint": false
    },
    {
      "code": "unauthorized",
      "http": 401,
      "retryable": false,
      "meaning": "No valid credential was presented.",
      "emitted_by_implemented_endpoint": false
    },
    {
      "code": "forbidden",
      "http": 403,
      "retryable": false,
      "meaning": "The credential is valid but its scope does not permit this.",
      "emitted_by_implemented_endpoint": false
    },
    {
      "code": "rate_limited",
      "http": 429,
      "retryable": true,
      "meaning": "Request budget exhausted. Retry after the interval in Retry-After.",
      "emitted_by_implemented_endpoint": false
    },
    {
      "code": "conflict",
      "http": 409,
      "retryable": false,
      "meaning": "The operation conflicts with the current state of the object.",
      "emitted_by_implemented_endpoint": false
    },
    {
      "code": "unavailable",
      "http": 503,
      "retryable": true,
      "meaning": "Temporarily unable to serve. Retry with backoff.",
      "emitted_by_implemented_endpoint": false
    },
    {
      "code": "internal_error",
      "http": 500,
      "retryable": true,
      "meaning": "An unexpected failure. Carries a request id and nothing else — no stack frame, no path, no internal identifier.",
      "emitted_by_implemented_endpoint": false
    }
  ]
}