PAYMENT_REQUIRED
A paid plan used up its monthly credits and has no bought credits left.
What this means
[02]PAYMENT_REQUIRED only happens on paid plans. Onto bills your monthly plan credits first, then your bought credits. When both are gone, the call fails with 402. The body includes `plan_limit` and `credits_remaining`. Free never gets 402. It gets RATE_LIMITED instead, because Free can't spill into bought credits.
When you'll see it
[03]HTTP 402. Body always includes code: "PAYMENT_REQUIRED". Branch on code, never on the human-readable message — wording can change without notice; the code is the stable contract.
Example response
[04]{
"status": "error",
"code": "PAYMENT_REQUIRED",
"message": "Monthly plan quota exceeded and credit balance is empty. Top up credits in the dashboard to continue.",
"plan_limit": 10000,
"credits_remaining": 0
}How to handle
[05]Buy credits at app.buildonto.dev/read/billing (packs from $5 to $200) or move to a bigger plan. Bought credits stack on top of any paid plan. Plan credits come back at the start of the next UTC month, so retrying now won't help.
Suggested handling in a Node client:
if (data.code === 'PAYMENT_REQUIRED') {
// Out of plan + credits. Don't retry blindly — escalate.
notifyOps('Onto credits exhausted; top up credits or upgrade plan');
throw new Error(data.message);
}Free plan: this month's credits are used up. They reset at the start of the next UTC month.
Too many requests running at once for your plan. Wait a second and retry.
The action needs a higher plan, such as buying credits on the Free plan.
See the full error index for the complete catalog with the handling switch statement covering every code at once.