---
title: Rate limits
description: 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:

```http
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:

```http
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
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](/developers/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](/developers/pagination).
- Do not poll jobs in a tight loop. See [Async operations](/developers/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.
