{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "title": "Deck error responses",
  "description": "JSON error contracts for Deck. Website misses use RFC 9457 problem+json plus a Deck `errors` array. The REST API at https://api.deck.co/v2 always returns a JSON `errors` array with machine-readable `type`/`code`, a `message`, a `resolution` hint when known, and a `request_id`.",
  "website": {
    "contentType": "application/problem+json",
    "status": [400, 404, 410, 429, 500],
    "schema": {
      "type": "object",
      "required": ["type", "title", "status", "code", "detail", "errors", "request_id"],
      "properties": {
        "type": { "type": "string", "format": "uri" },
        "title": { "type": "string" },
        "status": { "type": "integer" },
        "code": { "type": "string", "description": "Machine-readable error code" },
        "detail": { "type": "string", "description": "Human-readable message" },
        "message": { "type": "string" },
        "resolution": { "type": "string" },
        "errors": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["type", "code", "message"],
            "properties": {
              "type": { "type": "string" },
              "code": { "type": "string" },
              "message": { "type": "string" },
              "resolution": { "type": "string" },
              "field": { "type": ["string", "null"] }
            }
          }
        },
        "request_id": { "type": "string" },
        "see": { "type": "object", "additionalProperties": { "type": "string", "format": "uri" } }
      }
    },
    "example": {
      "type": "https://deck.co/errors.json#not-found",
      "title": "Not Found",
      "status": 404,
      "code": "not_found",
      "detail": "This path does not exist on deck.co.",
      "resolution": "Use the sitemap, llms.txt, docs index, OpenAPI spec, or MCP manifest.",
      "errors": [
        {
          "type": "request",
          "code": "not_found",
          "message": "This path does not exist on deck.co.",
          "resolution": "Start at https://deck.co/llms.txt or https://deck.co/sitemap.xml."
        }
      ],
      "request_id": "req_static_404",
      "see": {
        "sitemap": "https://deck.co/sitemap.xml",
        "llms": "https://deck.co/llms.txt",
        "docs": "https://docs.deck.co",
        "openapi": "https://deck.co/openapi.json"
      }
    }
  },
  "api": {
    "baseUrl": "https://api.deck.co/v2",
    "contentType": "application/json",
    "docs": "https://docs.deck.co/api/errors",
    "openapi": "https://deck.co/openapi.json",
    "status": "https://deck.co/api/status",
    "schema": {
      "type": "object",
      "required": ["errors", "request_id"],
      "properties": {
        "errors": {
          "type": "array",
          "items": {
            "type": "object",
            "required": ["type", "code", "message"],
            "properties": {
              "type": { "type": "string", "description": "Error category (request, auth, rate_limit, source, task, api, …)" },
              "code": { "type": "string", "description": "Machine-readable code for programmatic handling" },
              "message": { "type": "string", "description": "Human-readable explanation; do not branch on this string" },
              "resolution": { "type": "string", "description": "Hint for how an agent should recover" },
              "field": { "type": ["string", "null"] }
            }
          }
        },
        "request_id": { "type": "string" }
      }
    },
    "example": {
      "errors": [
        {
          "type": "request",
          "code": "api_key_invalid",
          "message": "The API key is not valid.",
          "resolution": "Create a key in https://console.deck.co and send `Authorization: Bearer <key>`."
        }
      ],
      "request_id": "req_a1b2c3d4"
    },
    "resolutionHints": {
      "api_key_invalid": "Create a key in https://console.deck.co and send `Authorization: Bearer <key>`.",
      "rate_limit_exceeded": "Back off and retry. Documented limit is 200 requests per 10 seconds per organization. Honor Retry-After and RateLimit headers when present.",
      "resource_not_found": "Confirm the resource id and API version (`/v2/`). See https://docs.deck.co/api-reference.",
      "input_missing": "Check the OpenAPI spec at https://deck.co/openapi.json for required fields.",
      "not_found": "This path does not exist. Use https://deck.co/sitemap.xml or https://deck.co/llms.txt."
    },
    "rateLimitHeaders": {
      "RateLimit": "limit=200, remaining=<n>, reset=<seconds>",
      "RateLimit-Policy": "200;w=10",
      "Retry-After": "seconds to wait on HTTP 429"
    }
  }
}