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), 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.
"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:
{
"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
- Wait
Retry-Afterseconds (orretryAfterfrom the body), then send the same request again. - Do not retry at once in a loop: every refused request in the window still counts against the
globallimit. - If you hit a limit often, spread the work: page through lists with the largest page size (Pagination and filtering), cache what does not change, and reuse a session instead of exchanging a key per request.
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), not 429. Examples here call the cloud, https://api.console.buildbase.app.
Next steps
- HTTP API errors - when a retry is safe.
- Idempotent requests - retry a write after a
429without doing it twice. - The OpenAPI spec - every operation's
x-rateLimit.