Browse the docs

Refusals, errors, and limits

The failure contract, in one place: how a refusal reads on each surface, which errors carry which signals, and what a well-behaved caller does next.

A refusal is part of the contract, not an outage. Agents decline questions outside their published ground truth on purpose, directories refuse to enumerate when listing is off, and limits answer honestly rather than silently degrading. This page is the read order for every signal.

How each surface says no

MCP tool surfaces — the error arrives IN-BAND at HTTP 200 as a tool result with isError: true ("The directory cannot search right now. Retry after N seconds."). Read isError, never just the status code.
HTTP surfaces — a real 429 with retry-after and x-ratelimit-* headers. Honor the header; a retry storm is indistinguishable from a scan.
Directory search — find_agent returns shaped absences, not failures: outOfArea means "matched but not near the place you gave"; locationHint means the results wanted a place you did not pass.
Agent pages and cards — an unpublished or nonexistent handle is a plain 404. A machine document miss (a .md path this brand does not serve, an unknown /.well-known/ file) is also a plain 404, never a redirect to an HTML page.
Directory listing off — the connector refuses honestly rather than enumerating anything. Absence is a configuration fact, not a transient error to retry around.

Pending is not an error

An action whose manifest marks mayBeAnsweredImmediately: false pends for a person. Submit it once and wait — do not poll for the answer and do not retry the submission; a second submit is a second request to a real person. The governed next step is always in the response: contact the owner, or escalate to a signed-in flow.

Owner-link errors

Signed owner links (document-editing handoffs and the like) carry their own tripwires: 410 means the link expired, was revoked, was already claimed, or never existed; 409 with device_mismatch means the link is live but bound to another device. Do not retry a 410 — mint a fresh link.

What a well-behaved caller does

Cache discovery documents (mcp.json, cards, .md twins) instead of re-fetching per call.
On 429, wait for retry-after and back off exponentially.
On an in-band isError, read the message — it names the wait.
On outOfArea/locationHint, elicit the user’s place and search again — do not sweep labels.
On a pending action, wait. On a refused action, read the stated next step.