Skip to Content
Baseera Docs

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.

CodeStatusMeaningRetry?
rate_limited429Too many requests in a minute. Includes retryAfter.Yes, after the delay
limit_reached429A monthly spending limit is full. No retryAfter.No, until the limit resets or is raised
eval_limit_reached429The 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.

LimitValue
New turns20 per minute per user, 300 per agent, 100 per tenant. Each is editable per agent in rateLimits. Tool-result continuations do not count.
Source links60 per minute per user
AI checks30 per minute per user, on top of the per-record cap
Feedback30 per minute per user and 600 per agent
Knowledge push1,000 items per minute per secret key. A batch of 100 counts 100.
Tenant uploads20 per minute per user and 30 per tenant
Server signals600 calls per minute per secret key and 1,200 per agent
Eval API120 calls per minute per secret key
Eval runs500 attempts per run, one run at a time per agent, 30 runs per agent per hour
Agent theme1,200 per minute per publishable key and 60 per network address
Agent logo600 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-After header, in seconds. It is exposed to browsers through CORS.
  • retryAfter in 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, no retryAfter) 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.)

Next steps

On this page