Rate limits and quotas

Two different kinds of limit apply to your account, and they are refused differently.

Request limits#

A limit is a number of requests per minute, counted per account, not per key or per IP. Your key, your session token and the web app share it. The window is fixed: it starts at your first request and lasts 60 seconds.

One counter, several ceilings#

The limits in this table that have their own number (all but the login row, the collections row and the last row) share one counter per account, and each endpoint compares that shared count with its own ceiling. A few endpoints that this guide does not describe have a number of their own too, and use the same counter. So the lowest ceiling in play wins: after 20 calls to GET /api/v1/profiles within a minute, POST /api/v1/agent/chat answers 429 even if you never called it, while POST /api/v1/chat, with its ceiling of 60, still works.

Plan for that:

• Do not poll GET /v1/models or GET /api/v1/profiles. Read them once and cache them.
• Treat 20 per minute as the budget of everything you do with /v1, not of each endpoint.
• Expect a coding assistant to use several requests per turn: the message, token counting and retries all count.
• The 300 per minute limit of the other endpoints is a separate counter, but native chat, the agent and embeddings calls also count against it. The /v1 endpoints and the profiles and version calls do not.

The headers#

Every response from a limited endpoint carries:

Requests that fail authentication carry none of them.

The 429 response#

On the endpoints with their own number, the body is {"message": "Too Many Attempts."}. On /api/v1 it is always JSON. On /v1 it is JSON when you send Accept: application/json, which every official SDK does, and an HTML page otherwise. On the 300 per minute limit, it is:

{ "codigo": "limite_de_requisicoes", "detail": "…" }

The sentence in detail is localized, so use codigo and Retry-After.

Token quotas#

The operator sets a daily, a weekly and a monthly token ceiling for each account group, and a ceiling of -1 means none. Tokens are the tokens of your successful calls, in and out, on every surface and every model, including the operator's own. The windows are in UTC: the day resets at midnight, the month on the first day, and the week every Wednesday at 14:00.

Read yours with GET /api/v1/usage. When you reach a ceiling, calls are refused with 403. It is 403 and not 429 on purpose: retrying will not help until the window resets.

How the refusal looks depends on the surface:

The message says which ceiling it was, but its text is not stable, so do not parse it.

Other limits of your group#

Besides tokens, the group can restrict:

• the models you may use. GET /api/auth/me shows them as allowed_models, where null means all;
• remote servers: some groups may only use the operator's local servers;
• attachments per message, on the native chat.

Each of these is refused the same way as a quota, with 403.

Size limits#

These are defaults. The first two are fixed by the API; the operator can change the others.