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

# Assistant and API retry guidance

> Distinguishing burst throttling, monthly exhaustion and rate-limiter availability.

**Effective date:** November 4, 2026 (UTC), in production.

**Scope:** REST API `/api/v1` burst responses and error results from the six
existing COLA Cloud MCP tools. Limits, monthly allowances and successful tool
schemas are unchanged. No data refresh or historical reprocessing is involved.

The API distinguishes a rate-limiter service failure (`503 limiter_unavailable`)
from an enforced burst limit (`429 rate_limit_exceeded`). Both continue to deny
the request. Burst `Retry-After` and `error.details.retry_after` report the
seconds until the next minute window, rounded up, instead of a constant 60.

Previously, MCP dropped retry/reset timing and suggested calling `get_plan` on
every 429. MCP now preserves bounded timing and meter details, advises waiting
before any next tool after burst rejection, and advises pausing monthly-exhausted
meters until reset or a confirmed entitlement change. It performs no automatic
retries and adds no billing links or tools.

**Your action:** distinguish `error.code` in your caller. Honor `Retry-After` for
burst or service-unavailable responses with a finite retry budget. Persist a
pause for `quota_exceeded` until `X-Quota-Reset` or confirmed entitlement change.
Do not immediately call `/usage` or `get_plan` after a burst rejection.

Reproducible examples: a burst response with `Retry-After: 23` becomes an MCP
error with `retry_after_seconds: 23`; a monthly error with
`X-Quota-Reset: 1793491200` carries `quota_reset_at: 2026-11-01T00:00:00.000Z`
and `retryable: false`. This timestamp is an example, not the current reset.

See [authentication and recovery guidance](https://docs.colacloud.us/authentication.md) for error codes and
request corrections, and [MCP release #15](https://github.com/cola-cloud-us/colacloud-worker/pull/15)
for the Worker implementation.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.