Errors and status codes

A tool's error comes back inside its result, as JSON, not as an HTTP status. Only a missing or invalid credential is an HTTP error: 401.

The error envelope

Every error has the same shape. code is stable: branch on it, never on message.

{
  "schema_version": "3.5",
  "error": {
    "code": "NOT_FOUND",
    "message": "No provision matching '999' in this title.",
    "retryable": false,
    "hint": "..."
  }
}

The error may also carry did_you_mean, candidates (for AMBIGUOUS_REFERENCE) and retry_after_seconds (for RATE_LIMITED). No error ever carries internal detail: a server fault returns a reference to quote to support instead.

The codes

Code	Meaning	Retryable	What to do
`NOT_FOUND`	Nothing matches the request	No	Check the id or number
`PROVISION_NOT_INGESTED`	The provision is in the structure, but its text is not held	No	Give the user the Federal Register link
`AMBIGUOUS_REFERENCE`	More than one thing matches; `candidates` lists them	No	Call again with one candidate's id
`INVALID_ARGUMENT`	A value is malformed or not one the tool accepts, or the response would be too large to return; the message shows the expected form or the parameters to narrow	No	Correct the value, or narrow the request
`VERSION_NOT_HELD`	No text in force on the requested `as_at` date is held	No	Use a date the held compilations cover, or omit `as_at`
`TITLE_NOT_IN_FORCE`	The title is not in force; its text is never served, for any date	No	Tell the user, show the `frl_link`, do not supply the text from elsewhere
`COMPILATION_NOT_CURRENT`	A newer compilation is registered and not yet held, and withholding is on	No	Say a newer compilation exists and give the link
`UNAUTHENTICATED`	The call could not be tied to an account or a valid key	No	Check the credential
`FORBIDDEN`	The account cannot use this tool: the subscription is not active, the feature is withdrawn, or the address is outside a key's allowlist	No	Read the message; renew, or check the allowlist
`INSUFFICIENT_SCOPE`	The connection, or a partner key's client, does not hold the scope this tool needs	No	Reconnect and approve the permissions, or add the scope to the client
`TERMS_REQUIRED`	A partner organisation has not accepted the current Hansard conditions of use	No	Accept them on the partner page
`RATE_LIMITED`	A partner key's client has used its calls for this minute or day	Yes	Wait `retry_after_seconds`, then retry
`INTERNAL_ERROR`	A fault on Advisor's side	Only if `retryable` is true	Retry once if retryable; otherwise quote the reference to support

TITLE_NOT_IN_FORCE and COMPILATION_NOT_CURRENT are answers about the law, not failures. Withholding is off today, so COMPILATION_NOT_CURRENT is not returned; superseded text is served with compilation.state set to not_current.

Responses over the size limit

A tool response is limited to 8,000 tokens. A response whose items are in one list is cut to fit, keeping the first items in the tool's own order, and says so: page.truncated for a result list, or truncated and truncation_note for a list in the tool's own shape. A response that cannot be cut that way, such as a graph's nodes and edges, is refused with INVALID_ARGUMENT, naming the parameters that narrow the request.

HTTP statuses

Status	When
401	No credential, or an invalid, revoked or expired one. The `WWW-Authenticate` header points to the discovery document
200	Every tool call that reached a tool, including one that returns an error envelope

Note: A subscriber whose AI Pro subscription has lapsed receives plain text from a paid tool, not an error envelope: a sentence with the renewal link. renew_subscription returns the same link.

What this means for your code