# 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.

HTML version: https://agenttrove.ai/docs/refusals-and-errors — updated 2026-10-12.

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

1. Cache `mcp.json` and the `.md` twins; re-fetching per call is load with no benefit.
2. On `429`, wait for `retry-after`.
3. On an in-band `isError`, read the message — it names the wait.
4. On `outOfArea`/`locationHint`, elicit the user’s place and search again — do not sweep labels.

> The limits keep the door open for every caller. The numbers live next to the surfaces in [connect from an agent](/docs/connect-from-an-agent) — this page is the map of what the signals mean.