# Documentation Page **Page:** kit/agent/bot-urls/errors [Download Raw Markdown](./kit/agent/bot-urls/errors.md) --- # Bot URL errors and limits A Bot URL refuses a request with one fixed error code. The code tells you what to do next: fix the request, ask the Bot's owner, or retry later. This page lists every code. ## Where the code is Errors returned before a stream starts carry the code twice: - in the `X-Hoody-Error-Code` response header, in capitals: `KEY_INVALID` - in the body, in lowercase: `key_invalid` The body uses the format of the door you called, so your SDK raises its usual error type: | Door | Error body | |---|---| | Any path beginning with `/v1/messages`, or any path beginning with `/v1` sent with an `anthropic-version` header | `{"type":"error","error":{"type":"authentication_error","message":"Missing or invalid key.","code":"key_invalid"}}` | | Other `/v1` paths | `{"error":{"message":"Missing or invalid key.","type":"authentication_error","param":null,"code":"key_invalid"}}` | | `/mcp`, request refused | JSON-RPC: `{"jsonrpc":"2.0","id":null,"error":{"code":-32000,"message":"Missing or invalid key.","data":{"code":"key_invalid"}}}`. Refusals before the MCP server reads the request use `id: null`; errors the MCP server answers keep the request id when there is one. A refusal before the MCP server reads the request (a key, a limit, a request it cannot read) has the HTTP status from the table below. An error the MCP server answers to a request with an `id` has that status from MCP version `2026-07-28` on, but stays HTTP 200 when the request names no MCP version (`Mcp-Protocol-Version`) or an earlier one; the body and `X-Hoody-Error-Code` still carry the code. A request with no `id` or a `null` one gets the table's status. Read `error.data.code`, and check for a JSON-RPC `error` even on HTTP 200. A few MCP protocol errors keep their standard number in `error.code` so MCP clients can act on them: `-32601` (no such method, `path_not_allowed`), and `-32602`, `-32020`, `-32021`, `-32022` (`invalid_request`). `-32022` (protocol version not supported) also lists the versions to use in `error.data.supported`, and the version you asked for in `error.data.requested` when it is a version date. | | `/mcp`, a tool failed | HTTP 200 with a tool result marked `isError: true`, whose text starts with `error :` | | `/`, `/SKILL.md` and anything else | Plain text: `key_invalid: Missing or invalid key.` | A stream that fails after it started ends with the door's own error frame, carrying the same code and message. Every error also carries `X-Request-Id` and `Cache-Control: no-store`. When the URL allows browser access, the error normally has CORS headers too, so a web page can read the code; in rare cases they are left out and the page sees only a failed request. ## Error codes ### Fix the request | Code | HTTP | Meaning | What to do | |---|---|---|---| | `https_required` | 426 | The request used `http://`, which is refused and never redirected. Depending on which Hoody server receives it, the answer is this code or the generic `bot_not_found`, and neither says whether the name exists. | Always use `https://`. A redirect would make your key travel a second time. | | `ipv4_required` | 403 | The request came over IPv6. | Call over IPv4. Bot URLs accept IPv4 only. | | `key_invalid` | 401 | No key, a malformed key, two different keys, or a key that is unknown or revoked. | Check the key you were given. Send it once. See [Where the key goes](/kit/agent/bot-urls/calling/#where-the-key-goes). | | `path_not_allowed` | 404 | The path is not one of the Bot's doors, whatever the method, `OPTIONS` included. On `/mcp`, the MCP method does not exist on a Bot (JSON-RPC `-32601`, HTTP 404). Before MCP version `2026-07-28`, a method MCP defines but a Bot does not serve gets HTTP 200, and a method name MCP does not know at all is refused as `invalid_request` (HTTP 400, JSON-RPC `-32000`, `id` null). | Use `/v1/...`, `/v1/messages`, `/mcp` or `/events`. Paths are matched exactly. On `/mcp`, call `tools/list` to see what the Bot offers. On `/events` it means the Bot has no [live events](/kit/agent/bot-urls/calling/#live-events) yet: poll instead. | | `method_not_allowed` | 405 | The path exists, but not for this method. The `Allow` header lists the right ones. | Use a listed method. `DELETE /mcp` is always refused: the MCP server keeps no session. | | `body_too_large` | 413 | The request body is over 8 MiB. | Send less. | | `invalid_request` | 400 | The body, the tool arguments or the MCP message is malformed; the last non-instruction message is not the user's, or does not contain only text; its text is over 64 KiB; the request holds only instructions, or its last message only `` notes; a `tool_choice` forces a tool; `n` is above 1; a token limit is below 1; `/mcp` received a batch (a JSON array of messages); or `GET /events` had a body or a malformed `Last-Event-ID`. On `/mcp`, a message over 64 KiB comes back as a tool result marked `isError: true`, with HTTP 200. | Fix the request. Send one JSON-RPC message per `/mcp` request. See [How the Bot reads a request](/kit/agent/bot-urls/calling/#how-the-bot-reads-a-request). | | `request_not_found` | 404 | The MCP `ref` is unknown or belongs to another key, or the approval handle is unknown, already closed or out of date. On `/mcp` this comes as a tool result marked `isError: true`, with HTTP 200. | For a `ref`, ask again. For an approval, read `status` or `updates` for current handles. | | `request_conflict` | 409 | An `Idempotency-Key` was reused with different content, or the approval changed while your answer was being applied. | Use a new key, or read `status` and answer again. | ### Ask the Bot's owner | Code | HTTP | Meaning | |---|---|---| | `bot_not_found` | 404 | No Bot answers at this address. The label is unknown, its URL was deleted, or its URL is detached. Right after a URL is detached, calls can still get `bot_disabled` with a valid key, or `key_invalid` without one, before `bot_not_found`. A plain `http://` request can get it too; see `https_required`. Opened in a browser tab over `https://` (not a `/v1` or `/mcp` path), this 404 shows as a short web page. Plain `http://` requests, SDKs, `curl` and the API paths get the usual code. | | `bot_disabled` | 403 | The Bot is turned off: by its owner, by Hoody, or because its computer is gone. | | `key_disabled` | 403 | Your key is paused or has expired. | | `ip_not_allowed` | 403 | Your key works only from certain IPv4 addresses, and this is not one of them. | | `cors_disabled` | 403 | A browser preflight was refused: the owner turned browser access off. Call from a server instead. | | `bot_upgrade_required` | 503 | The Bot's agent needs an update before it can serve public calls. | | `forbidden` | 403 | The Bot refused the action under its own rules. | Each of these stays the same until the owner changes something. Retrying does not help. ### Retry | Code | HTTP | Meaning | When to retry | |---|---|---|---| | `rate_limited` | 429 | Too many requests this minute, for your key or for the whole Bot, or a very high request rate from your IPv4 address. | After the seconds in `Retry-After`. | | `concurrency_limit` | 429 | Too many calls running at once, for your key or for the whole Bot, or the Bot is still answering another request or busy with voice work. On `/events`: too many event streams open, or the per-key or whole-Bot call-concurrency limit was reached while admitting the connection. | After `Retry-After` (1 second), or when one of your calls or streams finishes. | | `ip_blocked` | 429 | Too many wrong keys came from your IPv4 address. | After the seconds in `Retry-After`. | | `bot_starting` | 503 | The Bot's computer is waking up. | With backoff; see [Cold starts](#cold-starts). There is no `Retry-After`. | | `bot_unavailable` | 503 | The Bot cannot be reached for a moment, for example while its owner moves it. | With backoff. | | `upstream_timeout` | 504 | The Bot did not answer in time. | The request may have reached the Bot. Repeat a read (listing models, `status`, `updates`, `ask` with a `ref`) with backoff. Before repeating anything that changes things, read `status` or `updates`. For long work, see [Long answers](/kit/agent/bot-urls/calling/#long-answers). | | `upstream_error` | 502 | The Bot could not answer: its model or speech provider failed, it was unreachable, or the model could not take the output cap of a [side request](/kit/agent/bot-urls/calling/#side-requests). On `ask_audio` it can also mean the Bot cannot listen, and on `speak` that it cannot speak: the owner has not set up that half of voice, or the speech provider refused the owner's key. | The request may have reached the Bot. Repeat a read with backoff. Before repeating anything that changes things, read `status` or `updates`. For voice, check `voice` in `status` first: when `listen` is `false`, `ask_audio` cannot work, and when `speak` is `false`, `speak` cannot. Ask the owner instead of retrying. | | `internal_error` | 500 | Something unexpected failed. | The request may have reached the Bot. Repeat a read with backoff. Before repeating anything that changes things, read `status` or `updates`. Quote the `X-Request-Id` if it keeps happening. | A retry of a chat request with the same `Idempotency-Key` normally joins the running message or returns its saved answer instead of posting again. This is best effort, not a guarantee: see [Long answers](/kit/agent/bot-urls/calling/#long-answers) for how long keys are kept and when a retry becomes a new message. Before repeating anything that changes things, check with `status` or `updates`. ## Limits | Limit | Default | Owner can set | |---|---|---| | Requests per minute, per key | 60 | 1 to 600 | | Requests per minute, whole Bot | 120 | 1 to 3000 | | Calls at the same time, per key | 4 | 1 to 16 | | Calls at the same time, whole Bot | 8 | 1 to 32 | | Open event streams (`/events`) | 4 per key, 32 per Bot, 16 per IPv4 address | No | | Length of one event stream | 25 seconds at most; then it sends `end` and you reconnect | No | | Request body | 8 MiB | No | | Message text | 64 KiB (65,536 bytes of UTF-8, not characters); longer text is refused with `invalid_request` | No | | Pause while sending the request body | 30 seconds; then the connection is closed with no answer | No | | Silence on an open answer | 300 seconds; streams carry a keepalive at least every 30 seconds | No | How they count: - A minute is a calendar minute: the count starts again at second 0 of every minute. `Retry-After` on a per-key or per-Bot `rate_limited` gives the seconds left in the current one. A single IPv4 address that sends a very high request rate also gets `rate_limited`, with `Retry-After: 1`. - Every request forwarded to the Bot counts once, including polls, retries and requests the Bot answers with an error. `GET /v1/key` also counts once, although it does not reach the Bot. Other requests refused before forwarding, the keyless manual and browser preflights do not count. - A call counts as running until its last byte is sent, so an open stream holds a slot. If you disconnect, the slot is free at once, even when the Bot keeps working on what you asked. An event stream from `/events` holds no call slot; it counts against the event stream caps instead, and each connection counts as one request. - Only 429 answers carry `Retry-After`. Successful answers carry no rate-limit headers. - A request body that pauses for more than 30 seconds gets no answer: the connection is closed. The owner's access log shows it as `request_timeout`. These limits are for callers of one URL. How many Bot URLs a server can hold is a limit of the owner's plan: 5 on a free server, 25 on Plus, 250 on Pro and 5,000 on a bare-metal server. See [How many URLs a server allows](/kit/agent/bot-urls/create/#how-many-urls-a-server-allows). ### Wrong keys After 5 wrong keys from one IPv4 address within a minute, each further wrong key is answered one second late. After 20 wrong keys within 10 minutes, that address is blocked for 15 minutes with `ip_blocked`. Wrong keys are counted in short time steps, so the slowdown or the block can start slightly before these counts, never after. The block can cover other Bot URLs too, so a misconfigured client can lock out your other integrations from the same address. Fix the key before retrying. ## Cold starts A Bot whose computer is asleep wakes on the first call. Until it is ready, calls answer `503 bot_starting` without `Retry-After`. Retry with a bounded exponential backoff: ```typescript const sleep = (ms: number) => new Promise(r => setTimeout(r, ms)); // Refused before the Bot acted: safe to send again, whatever the request. const BEFORE_THE_BOT = new Set(['BOT_STARTING', 'BOT_UNAVAILABLE']); // The request may have reached the Bot: send again only a read. const MAY_HAVE_ACTED = new Set(['UPSTREAM_TIMEOUT', 'UPSTREAM_ERROR', 'INTERNAL_ERROR']); async function callBot( send: (signal: AbortSignal) => Promise, isRead: boolean, // true only for a request that changes nothing: models, status, updates, ask with a ref ): Promise { const deadline = Date.now() + 120_000; // give up after about 2 minutes let delay = 1000; // start at 1 second let last: Response | undefined; for (;;) { // A timer can fire late, so check the time left right before every attempt. const left = deadline - Date.now(); if (last && left <= 0) return last; const res = await send(AbortSignal.timeout(left)); // each attempt gets only the time left const code = res.headers.get('x-hoody-error-code') ?? ''; let wait: number; if (res.status === 429) { wait = Number(res.headers.get('retry-after')) * 1000; if (!(wait > 0)) return res; } else if (BEFORE_THE_BOT.has(code) || (isRead && MAY_HAVE_ACTED.has(code))) { wait = delay; delay = Math.min(delay * 2, 30_000); // double, at most 30 seconds } else { return res; // includes a message the Bot may have acted on: read status or updates before sending it again } if (wait >= deadline - Date.now()) return res; // no time left after the wait last = res; await sleep(wait); } } ``` Pass `signal` to `fetch`, so an attempt that would run past the deadline is aborted. A timeout or a network failure makes `callBot` reject instead of returning a response. Catch it, and for a request that changes things read `status` or `updates` before sending it again. The same loop handles `bot_unavailable`, and waits out a `429` when its `Retry-After` fits in the time left. An `ip_blocked` response is returned when its `Retry-After` does not fit; a fresh 15 minute block never does. `upstream_timeout`, `upstream_error` and `internal_error` can come after the request reached the Bot, so the loop repeats them only for a read. For a message or an answer to an approval it returns them: read `status` or `updates` to see what happened before you send it again. `bot_upgrade_required` is a 503 too, but only the owner can fix it, so the loop returns it at once. Send an `Idempotency-Key` header with chat requests you may retry, and a new unique key for every new message. A retry with the same key and content then normally gets the saved answer instead of posting the message again; [Long answers](/kit/agent/bot-urls/calling/#long-answers) has the details. ## What's Next - [Call a Bot URL](/kit/agent/bot-urls/calling/): doors, streaming and long answers. - [Status, access log and lifecycle](/kit/agent/bot-urls/status/): what the owner sees for each refused call.