Skip to content

Beta: these docs are still being updated. The next full update is on 18 November at 8 PM UTC. Docs in beta. Full update 18 Nov, 8 PM UTC.

Hoody.com

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.

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:

DoorError 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 refusedJSON-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 failedHTTP 200 with a tool result marked isError: true, whose text starts with error <code>:
/, /SKILL.md and anything elsePlain 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.

CodeHTTPMeaningWhat to do
https_required426The 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_required403The request came over IPv6.Call over IPv4. Bot URLs accept IPv4 only.
key_invalid401No 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.
path_not_allowed404The 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 yet: poll instead.
method_not_allowed405The 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_large413The request body is over 8 MiB.Send less.
invalid_request400The 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 <system-reminder> 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.
request_not_found404The 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_conflict409An 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.
CodeHTTPMeaning
bot_not_found404No 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_disabled403The Bot is turned off: by its owner, by Hoody, or because its computer is gone.
key_disabled403Your key is paused or has expired.
ip_not_allowed403Your key works only from certain IPv4 addresses, and this is not one of them.
cors_disabled403A browser preflight was refused: the owner turned browser access off. Call from a server instead.
bot_upgrade_required503The Bot’s agent needs an update before it can serve public calls.
forbidden403The Bot refused the action under its own rules.

Each of these stays the same until the owner changes something. Retrying does not help.

CodeHTTPMeaningWhen to retry
rate_limited429Too 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_limit429Too 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_blocked429Too many wrong keys came from your IPv4 address.After the seconds in Retry-After.
bot_starting503The Bot’s computer is waking up.With backoff; see Cold starts. There is no Retry-After.
bot_unavailable503The Bot cannot be reached for a moment, for example while its owner moves it.With backoff.
upstream_timeout504The 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.
upstream_error502The 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. 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_error500Something 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 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.

LimitDefaultOwner can set
Requests per minute, per key601 to 600
Requests per minute, whole Bot1201 to 3000
Calls at the same time, per key41 to 16
Calls at the same time, whole Bot81 to 32
Open event streams (/events)4 per key, 32 per Bot, 16 per IPv4 addressNo
Length of one event stream25 seconds at most; then it sends end and you reconnectNo
Request body8 MiBNo
Message text64 KiB (65,536 bytes of UTF-8, not characters); longer text is refused with invalid_requestNo
Pause while sending the request body30 seconds; then the connection is closed with no answerNo
Silence on an open answer300 seconds; streams carry a keepalive at least every 30 secondsNo

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.

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.

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:

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<Response>,
isRead: boolean, // true only for a request that changes nothing: models, status, updates, ask with a ref
): Promise<Response> {
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.