Tokens has two ways to pay for usage: a subscription plan with a credit allowance, and a prepaid wallet for pay-as-you-go. This page explains how plans, credits and the wallet fit together, and exactly what happens when something runs out. Current plans and prices are on pricing.
Subscription plans vs pay-as-you-go wallet#
| Plan | Wallet | |
|---|---|---|
| What you buy | A weekly or monthly allowance of credits | A USD balance |
| Good for | Steady daily use, predictable cost | Occasional use, or extra on top of a plan |
| Limits | Plan's usage windows, rate limit and concurrency | Rate limit and concurrency |
| Models | The models included in the plan | Every model sold pay-as-you-go |
| Renewal | One payment per period, renewed by you | Top up when you want |
You can have both. With a plan, usage is paid from the plan's credits first.
How credits work#
Plan allowances are measured in credits. By default 100 credits = 1 USD; the exact rate can vary by plan, and the plan page shows it. Every request costs what the model's catalog price says for the tokens it used (input, output and cache-read tokens), and that cost is deducted from your credits when the response finishes. Prices per model are on /models.
Plan credits belong to the billing period they were bought for.
Usage windows: 5-hour, weekly and monthly#
Some plans also spread the allowance over time with usage windows, so that a single heavy day can't burn a month's credits. A plan can have any of these:
| Window | How it resets |
|---|---|
| 5-hour session | Starts with your first request after the previous session ended, and resets exactly 5 hours later |
| Weekly | Every Monday at 00:00 UTC |
| Monthly | At the end of your billing period |
A window is measured either in credits or in number of requests, depending on the plan. You can see each window's use and reset time in the dashboard, with node tokens.mjs usage, or with GET /v1/tokens/usage. See usage, limits and alerts.
What happens when a window or your balance runs out#
A usage window is used up: 429 window_exhausted#
{
"error": {
"message": "Your plan's session_5h limit has been reached. Resets in 5400s. Upgrade your plan or wait for the window to reset: https://tokens.bd/dashboard/billing",
"type": "rate_limit_error",
"code": "window_exhausted",
"param": null,
"request_id": "..."
}
}The response has a Retry-After header with the number of seconds until the window resets. Wallet balance doesn't bypass a plan window: while a window is used up, requests on the plan wait for the reset. Don't retry in a tight loop; Retry-After can be hours.
Plan credits run out#
Each plan is set either to stop when its credits run out, or to continue from your wallet (pay-as-you-go fallback). On a fallback plan, requests carry on as long as the wallet has money. Otherwise they fail with 402 insufficient_credits until the next period or a new plan. If you're not sure how your plan behaves, ask support.
The wallet is low or empty#
- Low balance: if your balance can't cover the
max_tokensyou asked for, Tokens may lowermax_tokensto what the balance covers (never below 16). The answer comes back shorter, usually withfinish_reason: "length". Top up before long agent sessions. - Empty:
402 insufficient_credits. All 402 messages link to /dashboard/billing.
Other billing errors#
| HTTP | Code | Meaning |
|---|---|---|
| 402 | no_funding | No active plan and no wallet balance |
| 402 | outstanding_debt | A previous request left an unpaid amount; top up to clear it |
| 403 | tier_permission_denied | Your plan doesn't include this model and the wallet has no balance to pay for it |
| 403 | monthly_spend_cap_exceeded | The key's own monthly cap, not your account; see API keys |
The full list is in errors.
Top up the wallet#
Open /dashboard/billing and add funds. The minimum top-up is $5 or ৳500. The wallet is kept in USD; if you pay in taka, the amount is converted at the exchange rate locked when you start checkout. See paying in BDT. The Wallet page in the dashboard shows every credit and debit in a ledger.
A low-balance email alert is on by default and fires when the wallet drops below $5. You can switch it off under Notifications in the dashboard.
Renewal and cancellation#
- Renewal is a one-time payment per period. Nothing is charged automatically. Before the period ends you get a renewal reminder (if that notification is on), and you renew from /dashboard/billing.
- Cancelling stops the plan at the end of the current period. You keep the plan and its remaining credits until then.
- Upgrading is buying a different plan; compare them on pricing.
Coupons and referrals#
If you have a coupon code, enter it at plan checkout. The discount is shown before you pay.
The referral program gives you a link in the form /r/<code> under Referrals in the dashboard. When people you refer pay, a commission is credited to your wallet. Current terms are shown on the Referrals page.