Errors

Every line the server can return instead of an answer, what causes it, and what to do about it.

The server has two ways to refuse. A transport error is JSON-RPC or HTTP: the request never reached a tool. A tool line is a normal successful result whose text says no. Agents get this wrong in one direction: they check isError, see nothing, and treat a limit line as an answer. Match on the text.

Transport errors

These come back as JSON-RPC errors or plain HTTP, never as a content block.

HTTP	Body	Cause	Fix
`401`	`{"jsonrpc":"2.0","error":{"code":-32001,"message":"invalid key"},"id":null}`	An `Authorization: Bearer` header whose token resolves to no key: revoked, mistyped, or from another environment.	Send no header at all to fall back to the anonymous allowance, or mint a new key at wellworn.dev/keys.
`405`	`{"jsonrpc":"2.0","error":{"code":-32000,"message":"method not allowed"},"id":null}`	Any HTTP method other than `POST` on `/mcp`, including the `GET` some clients open for a server-sent stream.	The transport is stateless and has no stream to open. Configure the client for Streamable HTTP with POST only.
`406`	`{"jsonrpc":"2.0","error":{"code":-32000,"message":"Not Acceptable: Client must accept both application/json and text/event-stream"},"id":null}`	The `accept` header is missing one of the two media types.	Send `accept: application/json, text/event-stream`.
`400`	`Bad Request`, as HTML	The body is not parseable JSON.	Check the quoting in your shell before you check the server.
`413`	`Payload Too Large`, as HTML	The request body is over 64 KB.	No tool takes an argument near that size. The longest field in the whole set is `submit_trap`'s `fix`, at 1,200 characters.
`500`	`{"jsonrpc":"2.0","error":{"code":-32603,"message":"internal error"},"id":null}`	The request failed before the tool answered.	Retry once. Nothing was written.
`503`	`{"ok":false,"service":"mcp"}` on `/health`	The database or Redis is unreachable from the server.	Not yours to fix. `/health` returning `{"ok":true,…}` with a commit sha is the healthy answer.

Error messages never carry the reason in detail: a driver message would name the database host, so it goes to the server log instead of to the caller.

Tool lines

These arrive as an ordinary result with one text block. Only the first two set isError: true.

Line	Cause	What to do
`MCP error -32602: Input validation error: …`	An argument failed the tool's input schema: missing, empty after trimming, over its length, an array with too few or too many items, or an unknown property.	Read the tail of the message; it names the field and the rule. The argument tables on each tool page carry the same limits.
`MCP error -32602: Tool <name> not found`	The tool name is not one of the eight.	Call `tools/list` and use the names from it.
`internal error (ref 4f2a9c1b); try again in a moment`	The tool threw.	Retry once. If it repeats, send the ref: it matches a line in the server log.
`limit reached: <label> <used>/<cap> <period> (resets …). Free key or plans: https://wellworn.dev/pricing`	The window or the burst is spent, or the anonymous subnet throttle tripped.	Stop calling until `resets`. Limits explains which counter refused you.
`key required: create a free key at https://wellworn.dev/keys to submit traps`	`submit_trap` without a key.	Get a free key. This answer is free; it does not spend a call.

Nothing verified yet

A miss is not an error. It costs a call, it sets no error flag, and it means the corpus has no answer rather than that something went wrong.

Line	Tool
`no verified verdict yet for "…". Browse https://wellworn.dev/verdicts or request one at https://wellworn.dev/request`	`recommend`
`no verified comparison yet for "… vs …". Browse …`	`compare`
`no verified alternatives list yet for "…". Browse …`	`alternatives`
`no verified design verdict yet for "…". Browse …`	`design`
`no traps recorded for "…" yet. Hit one? submit_trap sends it to review.`	`traps`, library unknown
`TRAPS <name> <version>: none verified for this range.`	`traps`, library known and clean
`no trap with id …`	`traps` by id
`pass library (and optionally version) or id`	`traps` with no arguments
`no skill "…" yet. Browse https://wellworn.dev/skills`	`skill`
`no docs pointer for "…" yet`	`docs`

Treat a miss as permission to decide for yourself. Retrying the same words gets the same answer, and each retry costs another call.

The traps API

The plain-text endpoint answers in status codes rather than blocks.

Code	Body	Cause
`400`	`library is required`	The `library` parameter was missing or blank. Checked first, so it costs no call.
`401`	`invalid key`	The bearer token resolves to no key.
`204`	empty	The library is not in the corpus.
`429`	the limit line	The window is spent.