Rate limits and spend
Per-minute limits, the Retry-After header, how to handle 429 responses, and monthly spending caps.
Two kinds of limit can answer 429. A rate limit says slow down and try again soon. A spending limit says the monthly budget is full.
| Code | Status | Meaning | Retry? |
|---|---|---|---|
rate_limited | 429 | Too many requests in a minute. Includes retryAfter. | Yes, after the delay |
limit_reached | 429 | A monthly spending limit is full. No retryAfter. | No, until the limit resets or is raised |
eval_limit_reached | 429 | The eval run caps were reached. | After the hour passes |
Rate limits
Counted in the database, so two runtime instances cannot both take the last slot.
| Limit | Value |
|---|---|
| New turns | 20 per minute per user, 300 per agent, 100 per tenant. Each is editable per agent in rateLimits. Tool-result continuations do not count. |
| Source links | 60 per minute per user |
| AI checks | 30 per minute per user, on top of the per-record cap |
| Feedback | 30 per minute per user and 600 per agent |
| Knowledge push | 1,000 items per minute per secret key. A batch of 100 counts 100. |
| Tenant uploads | 20 per minute per user and 30 per tenant |
| Server signals | 600 calls per minute per secret key and 1,200 per agent |
| Eval API | 120 calls per minute per secret key |
| Eval runs | 500 attempts per run, one run at a time per agent, 30 runs per agent per hour |
| Agent theme | 1,200 per minute per publishable key and 60 per network address |
| Agent logo | 600 per minute per publishable key and 30 per network address |
Tool-result continuations are exempt from the turn limit because they belong to a turn that already passed. Refusing one would strand a half-finished turn.
Headers and body
There are no X-RateLimit-* headers. A refused call returns the delay in two places:
- The
Retry-Afterheader, in seconds. It is exposed to browsers through CORS. retryAfterin the error body, in seconds.
HTTP/1.1 429 Too Many Requests
Retry-After: 12
Content-Type: application/json
{ "error": { "code": "rate_limited", "message": "Too many requests. Try again in 12 seconds.", "retryAfter": 12 } }The delay is between 1 and 60 seconds.
Handle a 429
Wait for Retry-After, then retry. Add a little random jitter, and do not retry in a tight loop.
async function withRetry(send: () => Promise<Response>, attempts = 3): Promise<Response> {
for (let i = 0; ; i++) {
const response = await send();
if (response.status !== 429 || i >= attempts) return response;
const body = await response.clone().json();
if (body.error.code === "limit_reached") return response; // a monthly limit: waiting will not help
const seconds = Number(response.headers.get("retry-after") ?? body.error.retryAfter ?? 1);
await new Promise((resolve) => setTimeout(resolve, seconds * 1000 + Math.random() * 250));
}
}In the SDK, onError fires with { code, retryAfterMs } for a rate limit and the end user sees a short line saying the assistant is busy.
A provider can also rate limit the customer's own key. That is provider_rate_limited (HTTP 502), with retryAfter when the provider says how long.
Monthly spending limits
An owner or admin can give each agent a monthly limit in cost (USD), in tokens, or both. The first one reached counts. The organization can also set one default that every tenant gets, counted across all its agents. Periods are calendar months in UTC.
- At 80%, each owner gets one email per limit per period.
- At 100%, a new turn is refused with
limit_reached(HTTP 429, noretryAfter) before any model call. Nothing is created: no turn, no message. - Turns already running, and tool-result continuations of a turn that was let in, always finish.
- A session without a tenant has no tenant limit. It still counts against the agent's.
- A model without a known price is counted at the highest price Baseera knows, never as free. Token limits do not depend on prices.
The limit resets on the 1st of the month (UTC), or when the owner raises it. Chat and AI-check calls made for end users count. Eval runs and knowledge embeddings do not.
A turn that is let in reserves a small slice of the limit while it runs, so concurrent turns cannot all take the last slot. One turn can still push the total past the limit by what it costs beyond its slice. That overshoot is accepted and bounded by the number of turns in flight.
{ "error": { "code": "limit_reached", "message": "The monthly spending limit is reached." } }(The message text varies. Branch on code.)