Balance Alerts and Overdue Payments
Applicable roles: Organization (top-level user), sub-users, developers Updated: 2026-07-09
This article explains how the system behaves when your balance runs out or a limit is triggered (including error codes), the low-balance alert mechanism, and how to quickly restore service. After reading it, you'll be able to tell whether you're "out of money" or "being rate-limited," and know how to handle each case.
1. What Happens When the Balance Runs Out
In the new console, actual billing always deducts from the organization's balance pool. When the organization's balance is exhausted, calls from all Keys under it are rejected outright; when a sub-user's quota cap is used up, all Keys under that sub-user are rejected together.
By HTTP status code, these fall into two broad categories: "out of money / quota capped" (403 class) and "rate limit / quota triggered" (429 class):
| Scenario | HTTP Status Code | Meaning |
|---|---|---|
| Organization balance exhausted | 403 | Organization balance ≤ 0, all calls under it are rejected; recharge required |
| Sub-user quota cap used up | 403 | All Keys under that sub-user are rejected together; increase its quota |
| Key quota 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's concurrency cap; reduce concurrency or contact an admin to adjust the concurrency cap |
For specific error codes, refer to the
codefield actually returned by the interface; this table describes them by HTTP status class first. For complete error handling on the developer side, see Developer Guide · Error Codes and Troubleshooting.
Key Distinction: Organization Owes Balance vs. Sub-user Quota Exhausted
Both manifest as "calls being rejected," but the scope and handling differ:
| Situation | Scope of Impact | How to Recover |
|---|---|---|
| Organization balance in arrears | All sub-users and all Keys under the organization cannot make calls | Recharge the organization |
| A sub-user's quota exhausted | Only all Keys under that sub-user are rejected; other sub-users are unaffected | The organization raises the quota cap for that sub-user (provided the organization balance is still sufficient) |
If a sub-user has multiple Keys, they share the same quota cap (i.e., a cumulative consumption count against the quota cap); once the quota is exhausted, all of that sub-user's Keys are rejected at once, rather than just one of them. For the relationship between organization balance and sub-user quota, see Account System Explained.
2. Low-Balance Alert Mechanism
To avoid a sudden service interruption caused by the balance running out unnoticed, you can configure a low-balance alert to notify you in advance when the balance drops to a threshold.
Configurable Options
| Configuration | Description |
|---|---|
| Alert toggle | Whether to enable the balance alert |
| Threshold | The balance line that triggers the alert (configurable by amount) |
| Notification email | In addition to the account email, you can add extra recipients (e.g., finance or operations colleagues) |
The specific configurable fields (threshold type, whether percentages are supported, etc.) are subject to the actual settings in the console. We recommend adding finance/operations emails to the notification list so relevant colleagues receive alerts simultaneously.
3. Quick Recovery
Recovering service is fast, and takes effect immediately after a successful recharge or quota adjustment:
-
Insufficient organization balance: After recharging (see "Recharge and Redemption Codes"), the balance is credited immediately, and the next request can make calls.
-
Sub-user quota exhausted: The organization raises its quota cap, which takes effect immediately after adjustment.
-
Recharges/quota adjustments take effect immediately, with no need to log in again or recreate Keys.
-
During arrears, historical usage data and API Key configurations are unaffected, and can be used as usual once the balance/quota is restored.
4. Operational Recommendations for Organizations
| Recommendation | Reason |
|---|---|
| Set up low-balance alerts in advance | Avoid the whole team losing service unnoticed |
| Reserve ample quota for core sub-users | Prevent critical calls from failing due to quota caps |
| Regularly review consumption trends on the dashboard | Anticipate the rate of balance consumption and recharge in advance (see Billing and Usage Monitoring) |
| Configure additional notification emails | Let finance/operations receive alerts simultaneously |
Dashboard balance overview area:
5. FAQ
Q: What error is returned when the balance is 0?
A: It returns HTTP 403 (balance/quota class), and calls under the account are rejected. After recharging, service resumes on the next request. The specific error code is subject to what the interface actually returns.
Q: What's the difference between 429 and 403?
A: 403 means out of money / quota capped (resolved by recharging or raising the quota); 429 means a quota/rate limit was triggered (you need to wait for the quota window to reset or reduce concurrency). The two are handled entirely differently.
Q: Why do all of a sub-user's Keys suddenly fail while other sub-users work fine? A: It's very likely that the sub-user's quota cap is exhausted. All Keys under a sub-user share the same quota cap, and when the quota is used up, these Keys are all rejected together. The organization can raise its quota (the organization balance must be sufficient) to restore service.
Q: How long after recharging can calls resume? A: Immediately. After a successful recharge/quota adjustment, the next request can make calls normally.
Q: Will API Keys become invalid during arrears? A: No. The Key itself is retained; calls are simply rejected when the balance/quota is insufficient, and can be used as usual once restored.