# chargebee "api_error": plan quantity exceeds the configured limit

## TL;DR
The plan has a configured quantity ceiling and your request went past it. Raise the limit in the plan configuration (or pick a plan tier that allows the quantity), then resubmit. This is a config guardrail, not a gateway failure.

```text
chargebee "api_error": plan quantity exceeds the configured limit
```

## Steps

1. Read the error detail to get the plan, the requested quantity, and the configured limit. Success check: you can quote all three numbers.
2. Decide whether the quantity is legitimate: if yes, raise the plan's quantity limit in Chargebee; if no, fix the quantity in your code. Success check: the business decision is recorded, not guessed.
3. Update the plan configuration and retry the subscription change. Success check: the API accepts the new quantity.
4. If quantities change often, set the limit with headroom or remove the cap where the business allows it. Success check: routine growth no longer trips the guardrail.
5. Add an agent check before quantity updates: compare requested quantity to the plan limit and surface a warning instead of a failed API call. Success check: the next near-limit update warns first.

## When this applies

- Chargebee returns api_error because a quantity exceeds the plan's configured limit.
- Subscription upgrades or quantity updates are rejected.
- Onboarding flows break for customers with large seat counts.

## When it doesn't

- Payment failures on the subscription; those are gateway errors.
- Plan not found errors; those are id mismatches.
- Quantity limits you cannot change for contract reasons; escalate to the account owner.

## Tool + version compatibility

Chargebee subscriptions and plans API (all current API versions).

### "chargebee plan quantity limit exceeded"
Raise the configured limit or lower the requested quantity.

### "chargebee api_error quantity"
Read the limit from the plan config; the error rarely lies.

### "chargebee subscription quantity exceeds limit"
Legit growth means raising the cap; a bug means fixing the number.

## Why it happens

Chargebee plans can carry a maximum quantity as a guardrail against runaway seat counts. Most teams set it once at plan creation and forget it, then a big customer or an agent-driven bulk update crosses the line and every update 500s with api_error. The API is protecting you from a config you wrote; the fix is deciding whether the guardrail is still the right size.

## Edge cases / pitfalls

- Raising the limit changes billing exposure; get a human sign-off for large jumps.
- Some limits are contractual, not technical; check the customer agreement before raising.
- Agent bulk-update jobs should fetch the plan limit first and clamp or warn, not blast updates.
- Log the old and new limit with who changed it; quantity-cap changes are audit-relevant.

## Provenance

Resolved from the public thread: https://vectle.com/posts/pst_2epUphrTHfy1h8gS8KPtYg