# Rate limits

The request limits the BuildBase HTTP API enforces, per address, per API key and per route, the RateLimit headers it returns, and what to do on a 429.

## In short

To keep the service fast for everyone, BuildBase caps how many requests arrive in a short window. Ordinary use never comes near the caps. If a program sends too many, BuildBase answers `429 Too Many Requests` and says how many seconds to wait; after that wait the same request works again.

## The limits every request meets

A request passes every limiter in front of its route, and is refused by the first that is full. These apply to all of `/api`:

| Limiter  | Limit                     | Counted per                                     |
| -------- | ------------------------- | ----------------------------------------------- |
| `global` | 500 requests in 3 seconds | Caller's IP address                             |
| `apikey` | 1000 requests a minute    | Organization API key (requests with a key only) |

Then, by family:

| Limiter      | Limit                 | Counted per  | Applies to                                                                  |
| ------------ | --------------------- | ------------ | --------------------------------------------------------------------------- |
| `org-write`  | 1200 writes a minute  | Organization | Writes on the organization API, from every key and console session together |
| `server-api` | 300 requests a minute | API key      | The server API, `/api/v1/server/*`                                          |
| `companykey` | 300 requests a minute | Company key  | The company API, `/api/v1/company/*`                                        |
| `discovery`  | 120 requests a minute | IP address   | `/.well-known/*` and `/org/*` discovery documents                           |

## Route limits in the app API

Routes that sign people in, send codes or spend money have a tighter limit of their own, per IP address unless noted:

| Limiter          | Limit        | Routes                                                                 |
| ---------------- | ------------ | ---------------------------------------------------------------------- |
| `login`          | 20 a minute  | Password sign-in, registration, two-step sign-in, Google One Tap       |
| `auth`           | 30 a minute  | Consent, device sign-in and most other hosted sign-in steps            |
| `otp`            | 10 a minute  | Magic links, email and phone codes, password reset, email verification |
| `public-write`   | 10 a minute  | Uploads, cart quotes and coupons, beta sign-up, company admin changes  |
| `token-exchange` | 120 a minute | `POST /api/v1/public/token/exchange`                                   |
| `payment-method` | 10 a minute  | Saving a card, choosing the default card, paying an invoice            |
| `addon-purchase` | 30 a minute  | Buying, upgrading, reducing and cancelling add-ons                     |
| `credit`         | 30 a minute  | Consuming credits                                                      |
| `credit-hold`    | 60 a minute  | Reserving, settling and releasing credit holds                         |
| `dcr`            | 5 a minute   | OAuth dynamic client registration                                      |

Each operation lists every limiter in front of it in `x-rateLimit` ([The OpenAPI spec](/http-api/openapi)), outermost first: `prefix`, `windowMs`, `max`, `per` (`ip`, `key`, or the name of what else it counts by), and `counts: some` when some requests pass uncounted, such as `apikey` for requests without a key.

```json
"x-rateLimit": [
  { "prefix": "global", "windowMs": 3000, "max": 500, "per": "ip" },
  { "prefix": "apikey", "windowMs": 60000, "max": 1000, "per": "key", "counts": "some" },
  { "prefix": "token-exchange", "windowMs": 60000, "max": 120, "per": "ip" }
]
```

These are the defaults in the code. A self-hosted install can raise three of them through its environment: `API_KEY_RATE_LIMIT_MAX`, `ORG_WRITE_RATE_LIMIT_MAX` and `TOKEN_EXCHANGE_PER_MINUTE`.

## The headers

Every limiter that counts a request sets these on the response, so they describe the last limiter the request passed:

| Header                | Example    | Means                                 |
| --------------------- | ---------- | ------------------------------------- |
| `RateLimit-Policy`    | `120;w=60` | The limit and its window in seconds   |
| `RateLimit-Limit`     | `120`      | Requests allowed in the window        |
| `RateLimit-Remaining` | `117`      | Requests left in this window          |
| `RateLimit-Reset`     | `42`       | Seconds until the window starts again |
| `Retry-After`         | `42`       | On a `429` only: seconds to wait      |

The `429` body says the same, for a browser page that cannot read headers from another origin:

```json
{
  "success": false,
  "message": "Too many token exchange attempts. Please try again later.",
  "reason": "rate_limited",
  "retryAfter": 42
}
```

OAuth endpoints answer a `429` in OAuth's shape, with `error` beside these fields.

## What to do on a 429

1. Wait `Retry-After` seconds (or `retryAfter` from the body), then send the same request again.
2. Do not retry at once in a loop: every refused request in the window still counts against the `global` limit.
3. If you hit a limit often, spread the work: page through lists with the largest page size ([Pagination and filtering](/http-api/pagination-and-filtering)), cache what does not change, and reuse a session instead of exchanging a key per request.

```bash
curl -s -i "https://api.console.buildbase.app/api/v1/public/sessions" \
  -H "x-session-id: $BUILDBASE_SESSION_ID" | grep -i '^ratelimit\|^retry-after'
```

Limits are the same on every plan. What a plan sets is monthly quotas, which answer `402` ([HTTP API errors](/http-api/errors)), not `429`. Examples here call the cloud, [https://api.console.buildbase.app](https://api.console.buildbase.app).

## Next steps

- [HTTP API errors](/http-api/errors) - when a retry is safe.
- [Idempotent requests](/http-api/idempotency) - retry a write after a `429` without doing it twice.
- [The OpenAPI spec](/http-api/openapi) - every operation's `x-rateLimit`.
