Errors and walls

When a metered call cannot proceed, the API returns a structured error carrying one of these codes. Usage walls mean a spendable lane ran out; capacity walls mean a plan ceiling. Credits never lift a capacity wall.

Usage walls

Code	Meaning	Remedy
`free_pool_exhausted`	The free daily allowance is spent for today. Free-tier requests draw from a small daily pool that resets each day.	Wait for the daily reset, or subscribe for a weekly included allowance.
`subscription_required`	The operation bills against Usage Credits, and credits are a subscriber-only lane.	Subscribe (credits then work as overflow), or route the call through your own provider key (BYOK) or a local model.
`plan_allowance_exhausted`	The subscription's included usage allowance is spent for the current window.	Enable pay-as-you-go overflow to draw on your Credit balance, wait for the window to roll, or upgrade the plan.
`premium_allowance_exhausted`	The weekly sub-budget for premium-band models is spent; standard models still have allowance.	Switch to a standard model, enable pay-as-you-go overflow, or upgrade.
`credits_exhausted`	Pay-as-you-go overflow is on, but the Credit balance is empty.	Add Credits, or turn on Auto Top-Up.
`overflow_cap_reached`	The optional monthly cap you set on pay-as-you-go overflow has been reached.	Raise or remove the cap in billing settings.
`credit_spend_limit_exceeded`	The API key's own USD spend cap (lifetime, monthly, or daily) is exhausted. The account may still have budget; this key does not.	Raise the key's cap, mint a new key, or wait for the key's window to roll.
`org_seat_cap`	The organization has no free seats for this action.	An organization billing admin adds seats.
`org_budget`	The organization's spending budget for the period is exhausted.	An organization billing admin raises the budget.

Capacity walls

Code	Meaning	Remedy
`storage_full`	Drive storage has reached the plan's cap.	Delete or move files, or upgrade: caps are per plan (Free 1 GB up to 1 TB on Max). Credits never lift a capacity wall.
`max_workspaces`	The plan's workspace count limit is reached.	Delete an unused workspace or upgrade the plan.
`max_members`	The workspace is at its member limit for the plan.	Remove a member or upgrade the plan.
`max_connections`	The plan's provider-connection (BYOK) limit is reached.	Remove an unused connection or upgrade the plan.
`max_concurrent_runs`	Too many agent runs are in flight at once for the plan.	Wait for a run to finish or upgrade the plan.
`memory_full`	The agent's memory store is at its size cap.	Prune memory entries or upgrade the plan.
`max_computers`	The plan's computer count limit is reached.	Remove a computer or upgrade the plan.
`max_computer_storage`	Cloud-computer disk allocation is at the plan cap.	Shrink or delete volumes, or upgrade the plan.

Handling walls in code

Wall errors arrive with HTTP 402 or 429 and a JSON body carrying the code above. Retrying without changing anything will not clear a wall: switch models, enable overflow, raise the key cap, or upgrade, per the remedy column. Transient errors (5xx, timeouts) are separate and safe to retry with backoff.

Usage walls

Code	Meaning	Remedy
`free_pool_exhausted`	The free daily allowance is spent for today. Free-tier requests draw from a small daily pool that resets each day.	Wait for the daily reset, or subscribe for a weekly included allowance.
`subscription_required`	The operation bills against Usage Credits, and credits are a subscriber-only lane.	Subscribe (credits then work as overflow), or route the call through your own provider key (BYOK) or a local model.
`plan_allowance_exhausted`	The subscription's included usage allowance is spent for the current window.	Enable pay-as-you-go overflow to draw on your Credit balance, wait for the window to roll, or upgrade the plan.
`premium_allowance_exhausted`	The weekly sub-budget for premium-band models is spent; standard models still have allowance.	Switch to a standard model, enable pay-as-you-go overflow, or upgrade.
`credits_exhausted`	Pay-as-you-go overflow is on, but the Credit balance is empty.	Add Credits, or turn on Auto Top-Up.
`overflow_cap_reached`	The optional monthly cap you set on pay-as-you-go overflow has been reached.	Raise or remove the cap in billing settings.
`credit_spend_limit_exceeded`	The API key's own USD spend cap (lifetime, monthly, or daily) is exhausted. The account may still have budget; this key does not.	Raise the key's cap, mint a new key, or wait for the key's window to roll.
`org_seat_cap`	The organization has no free seats for this action.	An organization billing admin adds seats.
`org_budget`	The organization's spending budget for the period is exhausted.	An organization billing admin raises the budget.

Capacity walls

Code	Meaning	Remedy
`storage_full`	Drive storage has reached the plan's cap.	Delete or move files, or upgrade: caps are per plan (Free 1 GB up to 1 TB on Max). Credits never lift a capacity wall.
`max_workspaces`	The plan's workspace count limit is reached.	Delete an unused workspace or upgrade the plan.
`max_members`	The workspace is at its member limit for the plan.	Remove a member or upgrade the plan.
`max_connections`	The plan's provider-connection (BYOK) limit is reached.	Remove an unused connection or upgrade the plan.
`max_concurrent_runs`	Too many agent runs are in flight at once for the plan.	Wait for a run to finish or upgrade the plan.
`memory_full`	The agent's memory store is at its size cap.	Prune memory entries or upgrade the plan.
`max_computers`	The plan's computer count limit is reached.	Remove a computer or upgrade the plan.
`max_computer_storage`	Cloud-computer disk allocation is at the plan cap.	Shrink or delete volumes, or upgrade the plan.