# Rate limits

Limits per person, per API token and per team, the RateLimit headers on every answer, and what to do on a 429.

Source: https://docs.orbits.africa/api/rate-limits

Limits are token buckets: you can make a short burst of requests at once, then they refill at a steady rate. Over a limit, the API answers `429` with `Retry-After` and a problem document, and the request is not carried out.

## The limits

| Who | Allowance | Burst |
| --- | --- | --- |
| Each person, signed in | 1,200 requests a minute | 400 |
| Each API token | 300 requests a minute | 100 |
| Each team, its members and tokens together | 6,000 requests a minute | |
| Sign-in and account routes (`/v1/auth/…`, `/v1/me/…`) and invite lookups, per address | 300 requests a minute | |
| Asking for a sign-in email, per address | 30 a minute | |
| Sign-in emails to one email address | 5 in a row, then one every three minutes | |

A token has a budget of its own, apart from the person who made it, so a busy CI pipeline doesn't slow down that person in the dashboard. Signed-in requests are counted per person and per token, not per address, so many people behind one office network don't affect each other.

A team's budget is spent by everyone in it together, so a `429` on a team's route can be the team's budget rather than yours: `RateLimit-Scope: team` says so.

An address that keeps sending tokens the API refuses (300 a minute) is made to wait, even when it then sends a good one.

## Headers

Every signed-in answer carries your own budget, and every `429` the budget that ran out:

| Header | What it says |
| --- | --- |
| `RateLimit-Limit` | The bucket's size: how many requests can be made at once. |
| `RateLimit-Remaining` | Whole requests left in it now. |
| `RateLimit-Reset` | Seconds until it is full again. |
| `RateLimit-Scope` | Which budget: `user`, `token`, `team`, `address` or `email`. |
| `Retry-After` | On a `429` only: whole seconds until one request is allowed. |

```console
$ curl -i https://api.theorbits.app/v1/me -H "Authorization: Bearer $ORBITS_TOKEN"
HTTP/2 200
ratelimit-limit: 100
ratelimit-remaining: 99
ratelimit-reset: 1
ratelimit-scope: token
```

## On a 429

Wait `Retry-After` seconds, then send the request again (with the same `Idempotency-Key`, for a `POST` that takes one). Don't retry in a tight loop: every refused request still counts. To stay under the limits, read `RateLimit-Remaining`, poll a deployment every few seconds rather than continuously (or follow its log stream), and use `limit=100` when you read long lists. The CLI and the SDKs wait and retry by themselves.
