What HTTP 402 Means on a Prepaid API
An API request stops with HTTP 402 Payment Required. Before changing your prompt, replacing your key, or restarting your application, check what the service means by that response. On Vana API, the documentation identifies 402 as the signal that your balance has run out. Start with billing, not a configuration rewrite. ([vanaapi.com](https://vanaapi.com/plug-in?locale=en))
§ Step 1: Understand the status code
HTTP 402 has a name, but not a universal payment workflow. The HTTP specification reserves it for future use rather than defining a standard response body or recovery procedure. The provider’s documentation and the actual error message therefore matter more than assumptions based on the number alone. ([rfc-editor.org](https://www.rfc-editor.org/rfc/rfc9110.html))
For a prepaid integration, treat a documented insufficient-balance response as a request to check available credit. Do not assume it means your bank declined a payment: inspect the account and response details before deciding what needs fixing.
§ Step 2: Capture the actual error
Inspect the HTTP response or your client’s error details. Record enough information to distinguish a billing interruption from a separate integration problem:
- Status: Confirm that the response is actually 402.
- Message: Read the returned explanation rather than relying only on the client’s summary.
- Context: Record the request time, selected model, and any request identifier returned.
- Destination: Check which service and account the application is using.
Keep API keys and sensitive prompt content out of logs. If you contact support, share the diagnostic details without exposing credentials.
§ Step 3: Check the account behind the key
Open the account associated with the key your application actually loads. Check its available balance and recent usage. Pay particular attention when switching between local development, a deployed application, and a command-line tool: verify each environment rather than assuming they share credentials.
Vana API documents billing based on the tokens a request actually uses. When investigating depleted credit, review completed activity instead of estimating expenditure from the number of requests alone. ([vanaapi.com](https://vanaapi.com/plug-in?locale=en))
If you have not started yet, create a Vana API account, add prepaid credit, and keep its key associated with the correct environment.
§ Step 4: Restore credit before retrying
If the balance is depleted, add credit through the account’s payment flow. Confirm that the account reflects the updated available balance before resuming work. Do not treat a payment confirmation screen alone as proof that the API account is ready.
If credit already appears available, avoid making repeated payments as a debugging tactic. Recheck the account-key pairing, preserve the error details, and ask support to investigate the discrepancy.
§ Step 5: Send one small test request
Resume with a short prompt and a modest output limit. Keep the same client, model, and configuration initially so that you test the billing recovery without introducing unrelated changes.
Vana API provides connection instructions for Claude Code, Codex, OpenAI-compatible clients, and Gemini CLI. Follow the instructions for your existing client rather than changing protocols to troubleshoot an exhausted balance. ([vanaapi.com](https://vanaapi.com/plug-in?locale=en))
Confirm that the test completes, then restart the paused workload gradually. For an agent or batch job, inspect its saved progress first to avoid repeating work that already completed.
§ Step 6: Make recovery deliberate
In your application, handle a documented balance-related 402 as an actionable billing state. Pause the affected queue, notify the account owner, and retain enough job state to resume safely. Show a clear message such as Prepaid credit is exhausted; check billing before resuming.
Do not attach an unlimited retry loop. For Vana API’s documented exhausted-balance condition, repeated requests do not address the stated cause. Require a balance check or operator confirmation before restarting. ([vanaapi.com](https://vanaapi.com/plug-in?locale=en))
§ Step 7: Add a simple prevention routine
Review credit before long-running jobs, compare recent usage with your planned workload, and set a replenishment threshold appropriate to your budget. Use balance alerts if available; otherwise, schedule a manual check.
The practical sequence is straightforward: read the error, verify the account, restore credit, test once, and resume deliberately. Keep billing recovery separate from prompt and connection debugging.