Credits and 402s
Which 402 you got and what to do about it. INSUFFICIENT_CREDITS versus DATA_CREDITS_EXHAUSTED, the trial data credit, AI credits for deployed agents, and why UPSTREAM_CREDITS_EXHAUSTED is a 503.
A 402 means the call did not run because of money: there is not enough to pay for it, or the plan's included data credits cannot cover it. Nothing was charged. A 402 never heals by waiting, so never retry one on a timer. A person has to top up or confirm a plan, and then the same call works.
UPSTREAM_CREDITS_EXHAUSTED is the opposite case and is deliberately a 503, not a 402: our own account with an upstream provider is out. There is nothing you or the person you work for can pay to fix it.
01
Which one you got
| Code | Status | Who sees it | What happened |
|---|---|---|---|
INSUFFICIENT_CREDITS | 402 | Data calls from organizations on a managed plan or with no builder plan. Any organization whose AI credits run out while a deployed agent is running. | The balance cannot cover the call. For a data call the message names both numbers: Insufficient balance. Required: $X, available: $Y. |
DATA_CREDITS_EXHAUSTED | 402 | Builder plans and the no-card trial | The plan's included data credits, or the trial's data credit, cannot cover this call. error.upgrade (REST) or the tool result (MCP) carries an upgrade offer. |
UPSTREAM_CREDITS_EXHAUSTED | 503 | Anyone calling a curated data source | Our account with that source's upstream provider is out of quota. Not your balance, not your plan. |
02
INSUFFICIENT_CREDITS
Tell the person you work for what the call needed and what was available, using the numbers from the message, and ask them to add credits on the billing page of the superagnt app at https://app.superagnt.com. Retry once they have.
To check the balance yourself, call agnt_credits_balance over MCP or GET https://api.superagnt.com/v1/credits over REST. Both keep answering when everything else is refused.
AI credits for deployed agents
Data credits and AI credits are separate wallets. A deployed agent runs on AI credits, and when those run out a new run is refused with INSUFFICIENT_CREDITS and the message AI credits are exhausted. Add AI credits to continue running managed agents.
- Scheduled runs are skipped while AI credits are out, and the schedule picks up again on its own after a top-up.
- Queue items wait in the queue rather than failing, and are worked once credits are back.
- Plans include data credits, not AI credits. AI credits are always topped up in the superagnt app, on every plan and on the trial.
How the two wallets fill and drain is on Credits and wallets.
03
DATA_CREDITS_EXHAUSTED
On a builder plan or the trial, the plan is the budget, so the refusal comes with a way forward. The reason in the offer says which situation you are in:
| reason | What it means | What still works |
|---|---|---|
included_credits_exhausted | This billing period's included data credits are used up. | Every non-data tool. Data calls resume when the plan renews, or right after an upgrade. |
included_credits_insufficient | Some included credit is left, but this call needs more than that. Range and bulk endpoints reserve their maximum cost up front. | A cheaper data call, or this one with a lower max_cost_cents (max_cost_cents_per_record on bulk calls) where the endpoint takes one. The offer's data field has cost_cents and remaining_cents. |
trial_grant_insufficient | On the trial: the data credit left is less than this call costs. | Cheaper data calls may still fit. |
trial_data_grant_spent | On the trial: the one-time data credit is spent, so data calls are paused. | Everything else keeps working until the trial ends. |
What to do with the offer (relay human_step, share confirm_url, never pay yourself) is on Plan limits and upgrade offers.
The trial's data credit
The no-card trial includes a one-time data credit, held in the organization's purchased balance. agnt_credits_balance shows its state under builder_trial: what is left, how many billable calls count toward starting the trial clock, the end date, and whether the credit is spent. The trial includes no AI credits. The current amount and how the trial clock starts are on Plans and limits.
04
UPSTREAM_CREDITS_EXHAUSTED
The message is This data source is temporarily unavailable. Please try again shortly. It means our account with the upstream provider behind that source ran out of quota, which breaks that source for everyone at once. Our team is alerted automatically.
- Retry later with backoff. The call cost you nothing.
- Do not send the person you work for to the billing page. Topping up or upgrading does not fix it.
- Other data sources keep working, so continue with the rest of the task if you can.
- If the same source still fails this way after retries spread over several minutes, open a ticket with the source and the time (see Getting help).
05
Not a superagnt_ balance at all
A 402 or a 429 from a connection (a CRM, an outreach tool, a mailbox you connected with your own credential) is about your account with that vendor. superagnt_ credits and plans do not change it. See Connection failures.