Operating

Errors & rate limits

What each status means, and the budgets that produce a 429.

Errors are { "error": "<message>" } with a meaningful status. The OAuth token endpoint uses the OAuth 2.0 codes instead — invalid_grant, invalid_client, unsupported_grant_type — because a client library expects them.

Statuses

400bad request: A missing or malformed parameter: user_id that is not a UUID, a kind outside the three. Retrying unchanged will fail identically.
401not authenticated: Missing, unknown, revoked or expired credential. For a gat_ token, treat it as consent withdrawn and re-run sign-in.
404not found: The token resolves to a user or client that no longer exists.
429rate limited: Carries retry-after in seconds. Wait that long — not less.
5xxour fault: Retry with backoff. Usage and entitlement calls are safe to repeat; deduplication is on our side.

Budgets

Fixed windows, shared across all instances

/api/v1/* reads600 / minute: Counted per credential, so a noisy deployment cannot spend another product's budget.
/api/oauth/token60 / minute: Counted per client_id, which is what keeps a misbehaving integration from brute-forcing codes on everyone's behalf.
search (mobile API)120 / minute: Per caller.

Windows are fixed, not sliding: the counter resets at the boundary and retry-after tells you when that is. There is no burst allowance to discover by probing.

Operating

Errors & rate limits

What each status means, and the budgets that produce a 429.

Statuses

400bad request: A missing or malformed parameter: user_id that is not a UUID, a kind outside the three. Retrying unchanged will fail identically.
401not authenticated: Missing, unknown, revoked or expired credential. For a gat_ token, treat it as consent withdrawn and re-run sign-in.
404not found: The token resolves to a user or client that no longer exists.
429rate limited: Carries retry-after in seconds. Wait that long — not less.
5xxour fault: Retry with backoff. Usage and entitlement calls are safe to repeat; deduplication is on our side.

Budgets

Fixed windows, shared across all instances

/api/v1/* reads600 / minute: Counted per credential, so a noisy deployment cannot spend another product's budget.
/api/oauth/token60 / minute: Counted per client_id, which is what keeps a misbehaving integration from brute-forcing codes on everyone's behalf.
search (mobile API)120 / minute: Per caller.

Windows are fixed, not sliding: the counter resets at the boundary and retry-after tells you when that is. There is no burst allowance to discover by probing.