Errors and limits

REST statuses

Status	Code	Meaning
`400`	`INVALID_CURSOR`	The pagination cursor is malformed.
`401`	`UNAUTHORIZED`	The API key is missing or invalid.
`401`	`API_KEY_OWNER_INELIGIBLE`	The key’s owner account is inactive or has an unverified email.
`403`	`FORBIDDEN`	The key or token lacks the scope for this request.
`403`	`PARTNER_SUSPENDED`	The owner’s partner account is suspended.
`422`	`VALIDATION_ERROR`	A parameter is invalid, or two cannot be combined, such as `cursor` with `since`, or an ID field with its reference field.
`422`	`AMBIGUOUS_IDENTIFIER`	A trader or asset reference matches more than one entity. See below.
`422`	`BUCKET_LIMIT_EXCEEDED`	An activity summary window spans too many intervals. See Limits.
`429`	`RATE_LIMITED`	The key has used its request allowance. See Rate limits.

A 403 can come from a missing scope or from an account restriction, so read the error code before you act. A new key with the right scopes does not fix a suspended account. Contact support@centaur.io. Webhook routes also return 403 PARTNER_REQUIRED for accounts that are not partners. Missing or inaccessible stats IDs do not return 404. They appear in the response metadata. The generated endpoint pages show each read’s error examples. Log the requestId from every failure and include it when you contact support. Set explicit time bounds and limits when exploring large result sets. When a response is narrower than you expected, check the applied time bounds, and remember that rows outside your access are left out without a warning.

Ambiguous identifiers

AMBIGUOUS_IDENTIFIER means a value in traderRefs or assetRefs matches more than one entity. REST returns error.details.entity, error.details.ref, and error.details.candidates. Each candidate has a numeric id, a name, and a nullable slug. Asset candidates also have a nullable assetClass. MCP returns isError: true with the candidates’ IDs, names, and slugs in the error text. To retry, replace the *Refs field with its *Ids field and the intended candidate’s numeric ID. Do not send both fields. Retrying with a returned slug can fail again if the slug is shared. Unknown references do not cause this error. They match nothing, and other references in the same filter still apply. See identifier rules.

MCP failures

MCP calls fail for missing credentials, an invalid OAuth token or wrong audience, a token without a Centaur MCP scope, invalid tool arguments, or a used-up quota. OAuth failures include WWW-Authenticate metadata that points to the protected-resource metadata URL. Scope failures can include insufficient_scope. Invalid or wrong-audience tokens can include invalid_token.

Limits

Limit	Value
List page size	`limit` up to `200`. Partner feed: default `20`, maximum `100` groups.
Trader and asset identifiers	Up to `200` non-empty entries in each `traderIds`, `traderRefs`, `assetIds`, or `assetRefs` field, duplicates included. Larger lists fail without truncation.
Rankings and activity summaries	At most `50` rows or groups, with no pagination
Activity summary window	At most `168` intervals of the chosen `interval` (hour, day, or week) between `startTime` and `endTime`. A longer window returns `422` `BUCKET_LIMIT_EXCEEDED`. Bucket starts are aligned to the interval, so a window that does not start on an interval boundary can return one extra partial bucket.
Performance rankings	`startTime` must be at least the evaluation window before now. Otherwise `422`.
Position performance windows	`1D`, `7D`, and `30D` only. There is no `3D` window and no public close-return mode.

Guidance on current positioning, performance, and questions no single read answers is in Which read answers which question. Partial pages are covered in Pagination.

Rate limits

Each API key has a request allowance. The default is 1000 requests, refilled in full one hour after the previous refill. Limits vary by account and environment. A used-up allowance returns 429 RATE_LIMITED, with Retry-After when available. Treat it as a normal back-off-and-retry condition.

MCP quota

MCP has one usage quota per Centaur user, shared by every connected client. The default is 1000 operations per hour. Active partners get their Partner Tier quota, initially 10000 operations per hour. A schema-valid tools/call or resources/read uses one operation before it runs. Discovery, listing, authentication failures, validation failures, and quota rejections use none. A tool that hits the quota returns isError: true with details under io.centaur/mcp-quota. A resource read returns the equivalent JSON-RPC error. Both include the reset time when available.

Basics

Feed and activity

Summaries

Positions

Traders and assets

Position Intelligence

Webhooks

System

Changes