{
  "topic": {
    "id": "error-catalog",
    "name": "The error catalog",
    "kind": "support backbone",
    "about": "Every error the API returns carries a stable code, and the catalog gives each code its typical HTTP status, whether retrying can help, and what an agent should do next — so an agent branches on the code instead of parsing prose. The catalog is served whole and per code. The codes a pre-call or registration attempt most often meets are carried in this topic's record, verbatim from the catalog: the two pre-call request errors, the unreachable-server error (the one retryable error among them — the server could not be probed and nothing was registered), and the redirected-URL error (register the destination directly). This diagnostics surface adds one code of its own, for a topic name outside the set.",
    "entry_points": {
      "catalog": "https://www.rightshold.com/v1/errors",
      "one_code": "https://www.rightshold.com/v1/errors/{code}",
      "diagnostics": "https://www.rightshold.com/v1/diagnostics"
    },
    "checks": [
      "GET /v1/errors — the whole catalog: every code with its typical status, retryable flag and action.",
      "GET /v1/errors/<code> — one code's entry, for the exact error an answer carried."
    ],
    "outcomes": [
      {
        "signal": "retryable: true",
        "meaning": "The catalog says retrying can help — the failure is a state that can change (a server that could not be probed, a record not yet sealed).",
        "next_step": "Follow the code's action, then retry the original request; do not change the request's meaning to make the error go away."
      },
      {
        "signal": "retryable: false",
        "meaning": "Retrying the same request cannot help: the request itself, or a fact it names, has to change.",
        "next_step": "Make the change the code's action names — a corrected URL, a registered destination, a field within its stated shape — then send the corrected request."
      },
      {
        "signal": "diagnostic_not_found (404)",
        "meaning": "No diagnostic topic exists under that name: the topics are the fixed set listed at GET /v1/diagnostics.",
        "next_step": "List the topics at GET /v1/diagnostics and read the one that matches the failure in hand."
      }
    ],
    "record": {
      "catalog_codes": 481,
      "relevant_codes": [
        {
          "code": "invalid_server_url",
          "typical_status": 422,
          "retryable": false,
          "action": "Send the remote MCP server's https URL (http only for a loopback address). URLs naming — or resolving to — private, link-local or reserved addresses are not fetched."
        },
        {
          "code": "invalid_precall",
          "typical_status": 422,
          "retryable": false,
          "action": "Send ?url=<the MCP server's https URL> and optionally ?tool=<a tool name of 200 characters or fewer>."
        },
        {
          "code": "server_unreachable",
          "typical_status": 422,
          "retryable": true,
          "action": "The server could not be probed (MCP initialize and tools/list); nothing was registered. Check the URL and that the server is up, then retry."
        },
        {
          "code": "server_redirected",
          "typical_status": 422,
          "retryable": false,
          "action": "The URL redirects to another address; a redirecting URL is not registered, because the record would name one address while another server's definitions fill it. Register the destination URL directly."
        },
        {
          "code": "diagnostic_not_found",
          "typical_status": 404,
          "retryable": false,
          "action": "Check the diagnostic topic id; list or search first."
        }
      ]
    },
    "record_url": "https://www.rightshold.com/diagnostics/error-catalog"
  }
}