Errors

Refusal codes

15 codes, closed vocabulary (MCP charter 2026-09-04)·shape: status: refused + refusal.code + recover_with·an absence is never a zero

The fifteen codes

Code	Means	Way out
`BAKED_TOOL_REQUIRED`	The question has a typed tool that carries rules raw SQL gets wrong (one payment basis per median, floors, cut points).	Call the tool named in recover_with with the arguments it shows.
`RAW_SQL_REQUIRED`	No typed tool answers this; the raw door does.	Re-ask through query_substrate with the SQL in recover_with.
`VINTAGE_REQUIRED`	The table is annual or versioned and the question did not pin a year or version.	Add the year, quarter or version_id recover_with names.
`REQUIRED_FILTER_MISSING`	The table needs a filter before it can be read within budget (a state on hospital prices, a contract on Stars).	Add the filter recover_with names and re-issue.
`AMBIGUOUS_ENTITY`	A name matched more than one thing, or nothing we serve.	Use one of the accepted names in the message, or resolve_entity / resolve_provider first.
`UNSAFE_JOIN`	The join would blend grains or bases that must stay apart.	Join through the key how_to_join names, or ask for each side separately.
`NO_COVERAGE`	We do not hold what was asked for: the payer is not indexed, the tool is withdrawn, the year is outside the files.	recover_with names the nearest thing we do hold. This is an absence we can prove, never a zero.
`NO_DATA`	The question was understood and the filters matched nothing.	Widen one filter at a time; the answer names what was searched.
`METHOD_MISMATCH`	The request would compare two payment bases (per diem with fee schedule, percent of charges with a dollar).	Pick one basis; compare_hospital_rates segments them for you.
`SCAN_LIMIT_EXCEEDED`	The query would scan more than the budget allows, or ran past the 40 s synchronous window.	Narrow the predicate (one state, one code, one year), aggregate in SQL, or use the async lane on a paid plan.
`SUPPRESSED`	The source suppresses this cell (CMS prints * for 10 or fewer).	Ask at a coarser grain; the bounds are in the answer.
`QUARANTINED_METHOD`	The tool is quarantined by the live audit for a measured defect and will not execute.	recover_with names the tool that serves the same purpose.
`INVALID_ARGUMENTS`	The arguments did not match the tool's input model.	fields says what each one accepts and recover_with carries a corrected example. HTTP 400 on REST.
`DATA_ALLOWANCE_REACHED`	This account has been delivered its monthly data allowance.	detail.resets_on says when; ask for the aggregate rather than the rows. HTTP 429 on REST.
`PLAN_REQUIRED`	This account's plan does not include the door asked for (the async lane, paging).	detail.upgrade_url; the sync door still answers questions. HTTP 402 on REST.

A refusal, as served

{
  "status": "refused",
  "refusal": {
    "code": "REQUIRED_FILTER_MISSING",
    "message": "compare_hospital_rates reads hospital files one state at a time; pass state.",
    "recover_with": [{ "tool": "compare_hospital_rates", "args": { "billing_code": "70553", "state": "OH" } }]
  }
}

HTTP statuses on the REST door

Status	Codes	Means
401	unauthenticated / invalid_key	Missing, empty or unrecognised bearer key.
403	entitlement_denied / scope_forbidden	The key may not call this tool.
404	unknown_tool	No tool of that name on this door.
400	INVALID_ARGUMENTS, invalid_input	The body did not match the tool's input model.
402	PLAN_REQUIRED	The plan does not include this door.
422	every other charter refusal	Understood and declined, with recover_with.
429	DATA_ALLOWANCE_REACHED, rate_limit_exceeded	The monthly allowance or the per-second rate limit.
500	TOOL_FAILED, ENGINE_*	Our failure; the correlation id in the answer is what we read.

This page as markdown: /docs-md/errors.md · every page in one file: /llms-full.txt