Rate Limits & Quotas

Overview

Request Rate Limits

The 429 Contract

{
  "success": false,
  "error": "Rate limit exceeded. Please try again later."
}

• •Retry on 429, and only on 429 — a 402 will never succeed on retry.
• •Honour Retry-After when it is present. When it is absent, start at a few seconds and back off exponentially with jitter.
• •Cap total retries. A limit measured per minute clears in under a minute; something still failing after several minutes is a different problem.
• •Never retry in a tight loop. Retrying immediately is what turns a brief limit into a sustained one.

Quotas and the 402 Contract

{
  "error": "quota_exceeded",
  "upgrade_required": true,
  "meter": "projects",
  "limit": 3,
  "used": 3,
  "remaining": 0,
  "policy": "alert_then_block",
  "reason": "Project limit reached for your plan",
  "message": "Project limit reached for your plan"
}

{
  "detail": {
    "error": "quota_exceeded",
    "upgrade_required": true,
    "meter": "agent.prompt",
    "limit": 10,
    "used": 10,
    "remaining": 0,
    "policy": "block",
    "reason": "10 free AI queries this month used",
    "message": "10 free AI queries this month used"
  }
}

What Triggers a 402

Meters

Per-Request Limits

Request size

Pagination

Batch writes

AI and workflow bounds

Sessions

What This Page Does Not Tell You

• •There is no single published requests-per-second or requests-per-minute figure for an account or an API key. Limits are per surface, and the surfaces that carry one are listed above.
• •An API key can record an hourly request rate when it is created. That value is stored with the key but is not applied at the public API edge today, so it is not a control you can rely on — do not use it as a way to throttle a key.
• •The per-minute figures above can change with deployment sizing. They are what the platform enforces, not a contractual floor.
• •Self-hosted and on-premise deployments meter differently. Plan allowances are a hosted-platform concept; a self-hosted install is governed by its licence.

Designing for Limits

• •Send an explicit limit on every list call, and page with a cursor rather than a deep offset.
• •Prefer one filtered POST /query over pulling a collection and filtering client-side — the filtered call is one request against your allowance instead of many.
• •Use the aggregate endpoints for counts and sums instead of fetching rows to count them.
• •Batch writes, but keep batches modest and check the returned counts rather than the status code.
• •Cache reads that do not change often. Public reads are already cached briefly, so a tight polling loop mostly re-reads the same cached answer while still consuming your allowance.
• •Handle 429 with backoff and 402 by surfacing it, and never conflate the two in one retry path.
• •Read your usage on a schedule and alert before you hit a ceiling, rather than discovering it as a failed request on launch day.

Next Steps

• •Errors & Status Codes — the full status-code catalogue, including the failures that return 200.
• •Billing & Usage API — reading your usage and allowances programmatically.
• •Plans & Billing — the plan catalog, Power, credit packs, and overage handling.
• •Querying & Pagination — page sizes, cursors, and the filter grammar.
• •Going to Production — checking your plan before launch day.