Browse the docs

Refusals, errors, and limits

The failure contract for this brand’s machine surface: how a refusal reads, 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 site’s pages on purpose, and the connector refuses to enumerate when listing is off. This page is the read order for every signal.

How each surface says no

Directory connector — denials arrive 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 and back off exponentially.
Directory search — find_agent returns shaped absences: outOfArea means "matched but not near the place you gave"; locationHint means the results wanted a place you did not pass.
Agent pages — an unpublished, unlisted-or-mistyped, 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.
Listing off — the connector refuses honestly rather than enumerating anything. Absence is a configuration fact, not a transient error.

Pending is not an error

An action whose manifest marks mayBeAnsweredImmediately: false pends for a person. Submit once and wait — do not poll and do not re-submit; the governed next step is named in the response.

What a well-behaved caller does

Cache mcp.json and the .md twins; re-fetching per call is load with no benefit.
On 429, wait for retry-after.
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.