{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://tiffany.systems/api/schema/error.schema.json",
  "title": "ApiError",
  "description": "The envelope returned by an implemented Tiffany API endpoint when it fails. It does not govern requests to unknown or nonexistent paths: those never reach a Tiffany endpoint and are answered by the hosting layer, which may return its own native response. Fixed in advance so the shape cannot be invented differently later under pressure.",
  "x-schema-version": "1.0.0",
  "type": "object",
  "additionalProperties": false,
  "required": ["error"],
  "properties": {
    "error": {
      "type": "object", "additionalProperties": false, "required": ["code", "message", "retryable", "documentation"],
      "properties": {
        "code": {"type": "string", "enum": ["invalid_request", "not_found", "unsupported_version", "withdrawn_object", "superseded_object", "unauthorized", "forbidden", "rate_limited", "validation_failed", "conflict", "unavailable", "internal_error"]},
        "message": {"type": "string", "description": "Safe to show a user. Never contains a path, a stack frame, an internal identifier or any part of a credential."},
        "retryable": {"type": "boolean"},
        "documentation": {"type": "string"},
        "request_id": {"type": "string"},
        "field": {"type": "string", "description": "Present only for validation_failed, naming the offending input field."},
        "object": {"type": "object", "description": "Present for withdrawn_object and superseded_object: the identity and the version that replaced it, so a client can follow the history rather than guess."}
      }
    }
  }
}