Bitcall APIRate Limits
How request quotas are counted, resolved, and enforced.
The gateway enforces a fixed‑window rate limit on every authenticated request. Exceeding it returns 429 { "error": "RATE_LIMITED" }.
Counted per principal
Quota is counted per principal — the targetId:userId pair — not per key.
Minting more keys for the same user does not increase quota. All of a principal's keys draw from one shared bucket. To raise throughput, request a higher limit, not more keys.
Each window, a counter increments per request; when it passes the limit's max within the windowSec window, further requests are rejected until the window rolls over.
How the effective limit is resolved
For a given principal, the gateway resolves the limit in this order and uses the first that applies:
- Per‑principal override — a specific limit set for this
targetId:userId. - Per‑role default — the platform‑wide default for the key's role.
- Hard fallback —
{ windowSec: 60, max: 1000 }if nothing else is configured.
Admins can inspect the resolved value (and its source) with the rate/effective management action, and set defaults/overrides with rate/set-default / rate/set-override — see Key Management.
Handling 429
When you receive RATE_LIMITED:
- Back off and retry after the window (the default window is 60 seconds).
- Spread load rather than bursting — steady traffic stays under a fixed window more reliably than spikes.
- If you consistently need more, ask an admin to raise your principal's limit.
Rate limiting is best‑effort: if the counter store is briefly unavailable the gateway fails open (allows the request) rather than blocking traffic. Don't rely on it as a hard security control — it protects capacity, not authorization.