Limits & enforcement
ApiGo does not choose one limit and ignore the rest. A request must pass every applicable check before it reaches a model provider.
Request check order
The gateway returns the first failure it encounters.
| Order | Check | Scope | Typical result |
|---|---|---|---|
| 1 | API key exists and is active | API key | 401 invalid_api_key or 403 apikey_inactive |
| 2 | Workspace has available funds | Workspace | 402 insufficient_balance |
| 3 | Model and output-token policy allow the request | API key | 400 model_not_allowed or 400 max_output_tokens_exceeded |
| 4 | Day, rolling 7-day, and rolling 30-day spend caps have not been reached | API key | A specific 402 ..._limit_reached error |
| 5 | API key and Workspace RPM, TPM, and concurrency layers all have capacity | Both | A scope- and dimension-specific 429 with Retry-After |
| 6 | Provider accepts the request | Provider/account | Provider response and error format |
This order explains which error you see when several limits are exhausted at the same time. It does not make an earlier check “stronger” than a later check. All checks still apply.
Workspace balance
Balance belongs to the Workspace, not to an individual API key. Every key in that Workspace draws from the same funds.
- Personal workspaces use their available balance.
- Enterprise workspaces can use cash balance plus configured credit.
- The gateway checks that available funds are greater than zero when a request starts.
- The gateway does not reserve the estimated final cost before the request runs. An already admitted request can therefore settle after the balance crosses zero. Later requests are blocked.
- Top-ups, credits, and settled usage update the admission snapshot asynchronously. Refresh Billing and retry after the balance changes; do not assume propagation is instantaneous.
When funds are unavailable, the gateway returns 402 insufficient_balance. The API key remains valid and can be used again after funds are available.
API key spend caps
You can set three independent USD caps on an API key:
| Cap | Window | Recovery |
|---|---|---|
| Day | Current calendar day in the Workspace time zone | The next Workspace-local day |
| 7-day | Current day plus the previous 6 Workspace-local calendar days | As older daily spend leaves the window |
| 30-day | Current day plus the previous 29 Workspace-local calendar days | As older daily spend leaves the window |
Only successful, settled usage contributes to these windows. A new request is rejected once recorded spend is equal to or greater than a configured cap.
The check happens before the new request runs, while its final cost is known only after settlement. One request can therefore take recorded spend slightly above a cap. Spend caps are guardrails, not prepaid reservations.
- Unset or
0means unlimited for that spend window. - If multiple windows are exhausted, the gateway checks day, then 7-day, then 30-day.
- Configured caps must satisfy day ≤ 7-day ≤ 30-day.
- These caps apply only to the selected key. They are not Workspace-wide budgets.
RPM, TPM, and concurrency
Runtime limits protect capacity and latency. They do not replace balance or spend caps.
| Dimension | What it counts | How capacity returns |
|---|---|---|
| RPM | Admitted requests | Continuously refills; it does not reset at the top of a minute |
| TPM | Estimated input tokens at admission, then reconciled with actual input + output usage | Continuously refills |
| Concurrency | Requests currently in flight | Releases when a request completes, fails, or is cancelled |
TPM admission uses an estimate so the gateway can decide before contacting the provider. Actual usage is reconciled after the response. A response that has already started is not cut off because its final token count becomes larger than the estimate.
Two layers always apply
Every request is evaluated against two independent layers:
- The API key layer limits only that key.
- The Workspace layer aggregates traffic from every key in the Workspace and is the shared hard ceiling.
Both layers must pass. If a key is configured for 100 RPM and the Workspace for 1,000 RPM, the key can still use only 100 RPM. If other keys exhaust the Workspace pool first, this key can be rejected even when it is below 100 RPM.
Do not treat the two values as a single static min(key, workspace) number. The smaller configured number is a useful ceiling, but the Workspace layer has shared usage that changes independently.
Configuration precedence
| Layer | Value selection | Meaning of unset | Meaning of 0 |
|---|---|---|---|
| API key | The value stored on that key | No key-specific limit; the Workspace layer still applies | Disable only the key layer for that dimension |
| Workspace | Explicit Workspace value → default for the Workspace type → unlimited | Inherit the Workspace-type default | Explicitly disable the Workspace layer for that dimension |
A positive API key runtime limit cannot be configured above a positive Workspace ceiling. Setting the key layer to unlimited never bypasses a positive Workspace limit.
Defaults for new keys
The default API key limits under Workspace settings are a creation template:
- The template is copied into a new key when that key is created.
- Values explicitly entered while creating the key override the template.
- Changing the template later does not change existing keys.
- Workspace runtime limits remain a separate shared enforcement layer.
Runtime limit errors and retries
A runtime rejection returns HTTP 429, a specific error.code, and a Retry-After header.
| Layer | RPM | TPM | Concurrency |
|---|---|---|---|
| API key | api_key_rpm_exceeded |
api_key_tpm_exceeded |
api_key_concurrency_exceeded |
| Workspace | workspace_rpm_exceeded |
workspace_tpm_exceeded |
workspace_concurrency_exceeded |
Use the code to decide whether to reduce one key's traffic or the Workspace aggregate. Respect Retry-After, add jitter, and cap retries. Retrying a spend or balance 402 without changing the underlying condition will not help.
ApiGo coordinates runtime capacity across gateway instances. Configuration and balance changes propagate asynchronously, and distributed coordination can include a small bounded buffer around synchronization boundaries. Do not use RPM, TPM, or concurrency as an exact financial cutoff; use API key spend caps for cost guardrails.
Provider limits are separate
After ApiGo admits a request, the selected provider can still apply its own account, model, region, RPM, TPM, or concurrency limits. Provider errors keep the provider's HTTP status and response body, so their fields can differ from the ApiGo errors above.
A routing fallback can move eligible traffic to another configured model or provider. It cannot bypass Workspace funds, API key spend caps, or ApiGo runtime limits because those checks happen before provider routing.
Common examples
The key shows available RPM but receives workspace_rpm_exceeded.
Other keys consumed the shared Workspace pool. Reduce total Workspace traffic or request a larger Workspace limit.
The key is set to unlimited but still receives a Workspace 429.
Unlimited disables only the API key layer. The Workspace layer still applies.
The balance is positive but the request receives day_limit_reached.
The Workspace can still have funds while this key has exhausted its daily spend cap. Raise that key's cap or wait for its Workspace-local day to change.
The configured limit changed but the next request still sees the previous state.
Configuration is distributed asynchronously. Retry with bounded backoff. If it persists, keep the X-Request-Id and inspect Call Logs.
See API keys to configure key limits, Pricing and billing for funds, and Rate limits for client retry guidance.
