Rate limits
Koil's per-key and per-Organization request budgets, and how they differ from provider limits.
Every authenticated request is charged to two sliding-window budgets: the API key it presented, and the Organization that owns the key. One runaway integration cannot spend the budget of your other keys, and no Organization can spend another's. Requests with no key, or with a key Koil rejects, are charged to the client address instead, in separate budgets, so they never block a valid key sent from the same address. A request Koil could not validate (503 service_unavailable) is charged to no budget.
| Budget | Default |
|---|---|
| Per API key | 300 requests per minute |
| Per Organization, across its keys | 1,000 requests per minute |
| Per client address, for requests with no key or a rejected key | 60 requests per minute |
Authenticated responses carry RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset (seconds until the key's budget next frees a request). A request over budget answers 429 with rate_limit_exceeded and a Retry-After header: the seconds until the window frees a request. If Koil cannot check a budget at all, the request answers 503 with service_unavailable and a Retry-After header; nothing was attempted, so retry it.
Provider limits
These budgets protect Koil's API. Providers enforce their own limits on your app and on each account, and a provider throttle surfaces separately as platform_rate_limit, with Retry-After when the provider gives one. YouTube's daily quota, for example, is per Google Cloud project; see YouTube.