Skip to content
Soljio Docs
Esc
↑↓navigate↵open⌘Jpreview
On this page

Rate limits

The per-token and per-school request budgets, the RateLimit headers on every response, and how to back off and retry after a 429.

The API limits how fast an integration can send requests. Limits protect every school’s integrations from one runaway client. They apply to the HTTP API and also to tool calls from agents.

The budgets

Two token buckets apply to each authorized request:

Budget Capacity Refill
Per service token 120 requests 120 per minute, continuously
Per school 600 requests 600 per minute, continuously

Both must have room for a request to run. The school budget is shared by every token and every agent connection in that school.

  • Buckets refill continuously, not once a minute. A bucket that you emptied is partly refilled a few seconds later.
  • Every kind of request costs one unit: resource reads, HEAD requests, queries, commands, and replays of commands.
  • A request that is throttled does not run. A throttled command does not execute and does not save a result, so you can retry it with the same Idempotency-Key.
  • Another caller can use up the budget you were waiting for. Do not assume the first retry succeeds.
  • Requests rejected for an invalid credential or a missing scope still return 401 or 403, not 429. The rate limit is checked after authorization.
  • Public documentation endpoints, including the contract and the documentation MCP server, do not use these budgets.

Agent tool calls pass through the same checks. Each one draws from its own connection’s 120-per-minute budget and from the school’s 600-per-minute budget.

Headers

Every response carries the policy:

RateLimit-Policy: "token";q=120;w=60, "organization";q=600;w=60

Once a request is authorized and its quota has been evaluated, the response also carries a snapshot of what is left after that request:

RateLimit: "token";r=119;t=60, "organization";r=599;t=60

Both are Structured Fields lists in the style of the IETF RateLimit headers draft. Each quoted name identifies a policy.

Parameter Meaning
q The quota: how many requests the policy allows
w The policy window in seconds
r The requests still available after this attempt
t The effective window in seconds. It is 60. It is not a timestamp and not a promise that the budget resets all at once

RateLimit appears on successes, on errors raised by the operation, on HEAD responses, and on 429 responses. It is absent from errors produced before quota evaluation: a bad bearer header, an unknown path, a wrong method, a bad content type, an oversized body, a rejected Idempotency-Key or query string, and credential or scope failures (401 and 403). An error raised while the operation itself runs does include it.

When you get a 429

A throttled request returns 429 with the rate_limited code, both rate-limit headers, and Retry-After:

HTTP/2 429
retry-after: 3
ratelimit-policy: "token";q=120;w=60, "organization";q=600;w=60
ratelimit: "token";r=0;t=60, "organization";r=412;t=60

{"error":{"code":"rate_limited","message":"Too many requests. Retry after the indicated delay."},"request_id":"00000000-0000-4000-8000-000000000001"}

Retry-After is a positive whole number of seconds. Wait at least that long, then retry with the same key and the same body. If you get another 429, back off further. A sample retry loop is on the Idempotency page.

Staying under the limit

  • Read r from the RateLimit header and slow down before it reaches zero.
  • Use the largest page size an operation allows (100 for most lists) to cut the number of requests. See Pagination.
  • Do not poll jobs in a tight loop. See Async operations.
  • Give integrations their own tokens. Each token has its own 120-per-minute budget, but all of them share the school’s 600 per minute, so many busy tokens still compete.
  • Spread scheduled syncs across the minute instead of firing them all on the hour.

Agents

An agent whose call is throttled receives a tool error whose text reads rate_limited: Too many requests. Retry after the indicated delay. The delay itself is not included in the tool result, so an agent should wait a few seconds before it tries again.

Troubleshooting

  • 429 right after a quiet period. The school budget is shared. Another token or an agent connection may be using it.
  • No RateLimit header on an error. The request failed before quota evaluation. Fix the request first.
  • A long import hits the limit. Each batch of rows is one request. Send fewer, larger batches within the 250-row limit, and pause between them.

Was this page helpful?