> ## Documentation Index
> Fetch the complete documentation index at: https://docs.centaur.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Error expectations for REST requests and MCP tool calls.

## Common REST statuses

* `400` for malformed pagination cursors (`INVALID_CURSOR`)
* `401` for missing or invalid credentials
* `403` for keys that do not have access to the requested operation
* missing or inaccessible stats IDs are reported in response metadata rather than as `404`
* `422` for validation failures (`VALIDATION_ERROR`), including invalid parameter combinations such as passing both `cursor` and `since` to the partner feed
* `429` for rate limiting

Each API key has a request allowance. The default is `1000` requests, replenished in full one hour after the previous replenishment. Exhausting the allowance returns `429` with code `RATE_LIMITED` and, when available, a `Retry-After` header. Production limits vary by account or environment.

## Common MCP failures

* missing MCP credentials
* invalid OAuth access token or audience mismatch
* OAuth token without a supported Centaur MCP scope
* invalid tool arguments
* exhausted MCP usage quota

MCP OAuth failures include `WWW-Authenticate` metadata pointing to the protected resource metadata URL. Scope failures can include `insufficient_scope`; invalid or wrong-audience tokens can include `invalid_token`.

MCP has one usage quota per Centaur user across every connected client. The default is `1000` admitted operations per hour. Eligible paid partners receive their Partner Tier quota, initially `10000` operations per hour. A schema-valid `tools/call` or `resources/read` consumes one operation before execution. Discovery, listing, authentication failures, validation failures, and quota rejections do not consume usage.

Tool quota failures use `isError: true` and include stable details under `io.centaur/mcp-quota`. Resource quota failures use the equivalent JSON-RPC error. Both include the reset time when available.

## Operational guidance

* Log and preserve `requestId` from REST failures when asking for support.
* Prefer explicit time bounds and limits when an agent is exploring large result sets.
* If a response is narrower than expected, check the echoed applied bounds and remember that some rows can be silently suppressed by access or eligibility rules.
* Use the generated API reference for endpoint-specific error examples and response schemas.