payment_required and key_spend_limit_exceeded: what still works
payment_required is an organization wallet hold; key_spend_limit_exceeded is one key's monthly cap. Both arrive as HTTP 200 with isError true.
payment_required and key_spend_limit_exceeded are the two spend boundaries on CoreSpeed. The first is the organization's wallet: past the billing threshold, metered calls are refused. The second is one API key's monthly cap. Both come back as HTTP 200 with isError: true, both stop metered calls before the tool runs, and neither clears on retry.
| Aspect | payment_required | key_spend_limit_exceeded |
|---|---|---|
| Scope | the whole organization | one API key |
| Trigger | the wallet crossed its billing threshold | the month's usage reached the key's cap |
| Who is stopped | every caller, browser sign-ins included | that key only; teammates keep working |
| Who clears it | an org admin adds credit | the key's creator or an admin raises the cap, or the month rolls over |
| Clears on retry | no | no |
Which boundary did you hit?
| Code | Scope | Trigger | Who clears it | How |
|---|---|---|---|---|
payment_required | The whole organization | The wallet crossed its billing threshold | An org admin | Add credit: plan credits or a top-up |
key_spend_limit_exceeded | One API key | The month's recorded usage reached the key's cap | An org admin, or the key's creator | Raise the cap, or wait for the month to roll over |
org_suspended | The whole organization | An administrative action | Support | Adding balance does not clear it |
The difference between the first two is reach. A wallet hold stops every caller in the organization, including browser sign-ins, which have no cap of their own and only the wallet stop. A key cap stops that one key; a teammate's key, or your own browser sign-in, keeps working. Caps attach to API keys, as the billing page explains.
What keeps working during a hold?
A hold is a refusal of metered calls. Discovery, account reads and key management keep working. tools/list still answers, GET /connectors still answers, and an admin can still manage keys from the dashboard, the CLI or a signed-in client. Memory operations cost 0 credits per call. The agent can still read its memory, search it and save what it learned before stopping. Metered tools such as web__search, media__generate, social reads and connector calls are the ones refused.
The refusal happens before anything runs, so there is no partial side effect to clean up and no charge to dispute.
What does the error look like?
The HTTP status is 200. The signal is inside the result:
{
"result": {
"isError": true,
"structuredContent": {
"error": { "code": "payment_required" }
}
}
}Branch on structuredContent.error.code. Treating a 200 as success is the most common integration bug against this surface, and this is the case where it costs the most time: the agent believes the write happened and moves on. The two layers of failure are described on the error handling page. On the billing routes, rather than /mcp, the same conditions are plain HTTP: 402 for the wallet and 403 for a suspension.
How do you clear each one?
For payment_required, an org admin adds credit in Dashboard → Billing. On CoreSpeed Pro that means the monthly plan credits, which reset each month, or a top-up between $5 and $1,000, which never expires. The Free plan has no top-up: its 3,000 free credits cover metered actions for 90 days after the grant, and adding more means subscribing to Pro. Once credit lands, later calls run; nothing in the client changes.
For key_spend_limit_exceeded, raise the cap on that key in Dashboard → API keys or with the manage__keys_* tools from a signed-in client. Or wait: the cap is monthly and resets when the month rolls over. Rotating the key does not help; a fresh key with the same cap hits the same wall.
Do not retry in a loop. These codes belong to the list that never clears on retry, next to needs_reauth and jwt_session_required. Nothing changes until a person acts.
How do you avoid it next time?
Put a monthly cap on every API key, especially keys that an unattended job or an agent identity uses. A cap bounds what that one caller can spend before the wallet feels it. Read cs usage or Dashboard → Billing for the balance, and Dashboard → Activity for which calls cost what: each record references its charge and the dashboard joins the two.
One property to design around: caps are request-boundary guardrails, not reservations. A cap is checked when a call starts. An action already in flight, a long media generation for instance, can finish above the remaining amount before its cost is recorded. Set caps with that margin in mind.
FAQ
Can the agent retry payment_required after a few seconds? No. Nothing changes without an admin adding credit. Report it and stop.
Did the refused call cost anything? No. The refusal happens before the tool runs, and only successful metered actions are charged.
Does a key cap stop my teammates? No. The cap belongs to that key. A wallet hold is the one that stops everyone.
Is org_suspended a billing problem? No. It is administrative, is not cleared by adding balance, and goes to support.