# payment_required and key_spend_limit_exceeded: what still works (/blog/payment-required-and-spend-limit-errors)

![Illustration: A small friendly robot with a round camera-eye head stands before a vending machine with an empty coin slot and a small flag raised.](/blog/payment-required-and-spend-limit-errors/hero.webp)

`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.

**Org hold or key cap**

|                 | 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                                                                  |

org\_suspended looks similar and is different: administrative, not cleared by balance, goes to support.

Both arrive as HTTP 200 with isError true, before the tool runs.

## Which boundary did you hit? \[#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](/docs/billing) explains.

## What keeps working during a hold? \[#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? \[#what-does-the-error-look-like]

The HTTP status is `200`. The signal is inside the result:

```json
{
  "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](/docs/errors). 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? \[#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? \[#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 \[#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.