When an agent tries to spend credits it does not have, the API answers with HTTP 402 rather than failing silently or producing empty results. The response body says what is missing and includes the URL that fixes it.
The same condition surfaces differently depending on the client:
- REST API - status 402 with a message and a link to top up or pick a plan.
- CLI - exit code 5, which means payment required. Scripts and CI can branch on it directly.
- MCP clients - the agent reports the message back in the conversation, usually as 'your credits are used up'.
To resume:
- Open Home and top up the wallet, or pick a plan in Profile → Billing.
- Credits are booked as soon as payment completes.
- Re-run the same command. Nothing needs to be reconfigured, and API keys stay valid throughout.
Screenshot: A terminal showing the CLI payment-required message and exit code
A 402 can also mean something other than an empty balance. If the message mentions confirming your email, the 25 starter credits are waiting behind email confirmation. If it mentions starter credits already claimed for this mailbox, the one-time grant was used and the wallet is the next step.
Free operations are never blocked by a 402: counts and redacted previews keep working while you sort the balance out.