Balance Alerts & Arrears
Applies to: Organization (top-level user), Subuser, Developer Updated: 2026-07-02
This article explains what the system does when the balance is exhausted or a limit is triggered (including error codes), the low-balance alert mechanism, and how to restore service quickly. Read this and you'll be able to tell "out of money" from "rate-limited", and know how to handle each.
1. What Happens When the Balance Is Exhausted
In the new console, actual billing always deducts from the organization balance pool. When the organization balance is exhausted, calls from all Keys under it are rejected outright; when a subuser's quota limit is used up, all Keys under that subuser are rejected together.
By HTTP status code, this splits into two broad categories: "out of money / quota cap reached" (403 class) and "rate limit / quota limit triggered" (429 class):
| Scenario | HTTP status code | Meaning |
|---|---|---|
| Organization balance exhausted | 403 | Organization balance ≤ 0; all calls under it rejected; top up needed |
| Subuser quota limit used up | 403 | All Keys under that subuser rejected together; raise its quota |
| Key limit exhausted (5h / 1d / 7d window, if enabled) | 429 | The Key's quota for the corresponding time window is used up; wait for the window to reset |
| Organization concurrency exceeded | 429 | Instantaneous concurrency exceeds the organization concurrency limit; reduce concurrency or contact the administrator to adjust the concurrency limit |
For the exact error code, rely on the
codefield actually returned by the API; this table describes by HTTP status class first. For complete error handling on the developer side, see Developer Guide · Errors & Troubleshooting.
Key Distinction: Organization Arrears vs. Subuser Quota Used Up
Both manifest as "call rejected", but the scope and handling differ:
| Situation | Scope of impact | How to recover |
|---|---|---|
| Organization balance in arrears | All subusers and all Keys under the organization cannot make calls | Top up the organization |
| A subuser's quota used up | Only all Keys under that subuser are rejected; other subusers are unaffected | The organization raises that subuser's quota limit (provided the organization balance is still sufficient) |
If a subuser has multiple Keys, they share the same quota limit (i.e. the cumulative-spend counter against the quota limit); once the quota is used up, all of that subuser's Keys are rejected at the same time, not just one of them. For the relationship between organization balance and subuser quota, see Three-Tier Account Hierarchy.
2. Low-Balance Alert Mechanism
To avoid the balance being exhausted unnoticed and causing a sudden service outage, you can configure a low-balance alert to notify you in advance when the balance drops to a threshold.
Configurable Options
| Setting | Description |
|---|---|
| Alert toggle | Whether to enable balance alerts |
| Threshold | The balance line that triggers the alert (configurable by amount) |
| Notification email | In addition to the account email, you can add recipients (e.g. finance or ops colleagues) |
The exact configurable fields (threshold type, whether percentages are supported, etc.) follow the actual settings in the console. We recommend adding finance/ops emails to the notification list so relevant colleagues receive the alert as well.
3. Fast Recovery
Service recovers quickly and takes effect immediately after a successful top-up/quota adjustment:
Insufficient organization balance: After topping up (see "Top-up & Redemption Codes"), funds arrive immediately and the next request can make a call.
Subuser quota used up: The organization raises its quota limit, effective immediately after adjustment.
Top-up/quota adjustment takes effect immediately, with no need to log in again or recreate Keys.
During arrears, historical usage data and API Key configuration are unaffected, and can be used as usual once the balance/quota is restored.
4. Operational Advice for Organizations
| Advice | Reason |
|---|---|
| Set up low-balance alerts in advance | Avoid the whole team losing service unnoticed |
| Reserve ample quota for core subusers | Prevent critical calls from failing due to a quota cap |
| Regularly review the dashboard spending trend | Anticipate the balance consumption rate and top up early (see Billing & Usage Monitoring) |
| Configure additional notification emails | Let finance/ops receive alerts as well |
5. FAQ
Q: What error does a call return when the balance is 0? A: It returns HTTP 403 (balance/quota class), and calls under it are rejected. After topping up, the next request recovers. Rely on the API's actual returned code for the exact error.
Q: What's the difference between 429 and 403? A: 403 means out of money / quota cap reached (solved by topping up or raising the quota); 429 means a rate limit / quota limit was triggered (you need to wait for the limit window to reset or reduce concurrency). The two are handled entirely differently.
Q: One subuser's Keys all suddenly fail while other subusers are fine -- why? A: Most likely that subuser's quota limit is used up. All Keys under a subuser share the same quota limit, so when the quota is exhausted these Keys are rejected together. The organization raising its quota (with sufficient organization balance) will restore it.
Q: How long after topping up can I call again? A: Immediately. After a successful top-up/quota adjustment, the next request can call normally.
Q: Will API Keys become invalid during arrears? A: No. The Key itself is retained; calls are merely rejected when the balance/quota is insufficient, and it works as usual once restored.
Contact Us
- Email: support_cloudrouter@clouditera.com
- QQ community: 712273971
- Platform URL: cloudrouter.online