Skip to content
BuildBase
HTTP API menu

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:

LimiterLimitCounted per
global500 requests in 3 secondsCaller's IP address
apikey1000 requests a minuteOrganization API key (requests with a key only)

Then, by family:

LimiterLimitCounted perApplies to
org-write1200 writes a minuteOrganizationWrites on the organization API, from every key and console session together
server-api300 requests a minuteAPI keyThe server API, /api/v1/server/*
companykey300 requests a minuteCompany keyThe company API, /api/v1/company/*
discovery120 requests a minuteIP 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:

LimiterLimitRoutes
login20 a minutePassword sign-in, registration, two-step sign-in, Google One Tap
auth30 a minuteConsent, device sign-in and most other hosted sign-in steps
otp10 a minuteMagic links, email and phone codes, password reset, email verification
public-write10 a minuteUploads, cart quotes and coupons, beta sign-up, company admin changes
token-exchange120 a minutePOST /api/v1/public/token/exchange
payment-method10 a minuteSaving a card, choosing the default card, paying an invoice
addon-purchase30 a minuteBuying, upgrading, reducing and cancelling add-ons
credit30 a minuteConsuming credits
credit-hold60 a minuteReserving, settling and releasing credit holds
dcr5 a minuteOAuth 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:

HeaderExampleMeans
RateLimit-Policy120;w=60The limit and its window in seconds
RateLimit-Limit120Requests allowed in the window
RateLimit-Remaining117Requests left in this window
RateLimit-Reset42Seconds until the window starts again
Retry-After42On 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

  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), 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