Bitcall APIRate Limits
How request quotas are counted and what to do when you hit one.
The gateway enforces a fixed-window rate limit on every authenticated request. Exceeding it returns 429:
{
"error": {
"code": "RATE_LIMITED",
"message": "Too many requests. Retry after the interval in `Retry-After`.",
"requestId": "9f1c7b2e-4a83-4d21-9c55-1f0b3a7e2d64"
}
}The response carries a Retry-After header giving the number of seconds to wait. Read it rather than guessing — it is the authoritative answer.
Counted per account, not per key
The allowance is your account's, and every key on that account spends from the same one. Two keys do not get you twice the requests — they get you two credentials sharing a single allowance.
Issuing more keys does not increase throughput. Separate keys are for separating your integrations — so you can revoke one without an outage everywhere — not for buying headroom. If you need more, ask your provider to raise the limit.
Within each window a counter increments per request. Once it passes the limit, further requests are rejected until the window rolls over. The default window is 60 seconds.
Failed authentication is limited per IP
Separately from your account's allowance, the gateway counts failed authentication
attempts per source IP: a wrong secret, an unknown, revoked or expired key, or a request
from an IP the key does not allow. After 30 failures within 60 seconds, that IP gets
429 RATE_LIMITED for the rest of the window, even with correct credentials, and the
response carries Retry-After.
If you suddenly get 429 on every request after a credentials change, this is the likely
cause: a deploy shipped a wrong or rotated secret and retried it in a loop. Fix the
secret, then wait for Retry-After before retrying. Requests sent with no
credentials do not count toward this limit.
Handling a 429
- Wait for
Retry-After, then retry. The value is in seconds. - Spread load rather than bursting. A fixed window forgives steady traffic far better than spikes — the same total volume sent evenly may never hit the limit at all.
- Back off on repeats. If you are being limited continuously, add exponential backoff so retries do not become the load.
- If you consistently need more headroom, ask your provider to raise your limit.
Rate limiting protects capacity, not authorization. If the counter store is briefly unavailable the gateway fails open and allows the request rather than blocking traffic — so never treat a limit as a security control.