Limits and policies
Limits are enforced by gate policies and meter pricing, while plans decide who can reach those limits.
This guide focuses on the packaging boundaries developers should model.
Prereqs
- You use authorize then commit: Tutorial: authorize then commit.
What a plan does and does not do
- A plan grants access scope through entitlements for resources whose effective
entitlement_requiredistrue. - A plan can select a gate policy bundle (directly or via purchased prices).
- A plan does not redefine meter unit prices per plan.
- Meter prices stay catalog/meter driven; plans influence behavior by access scope and purchased quantities.
Access and limits are separate configuration surfaces
Treat access and limits as two linked but independent decisions:
- Entitlements decide whether an entitlement-required feature or feature family is allowed.
- Gate policies and bundles decide runtime limits such as quota, rate, seats, and related hints.
This means:
- If effective
entitlement_required=false, all accounts on the effective plan path can reach that feature without an explicit entitlement entry, but runtime usage can still be limited by gate policies and bundles. - If effective
entitlement_required=true, the account still needs an entitlement allow path, and runtime usage can also be limited by gate policies and bundles. - Do not model this as one per-plan list of allowed resources plus limits; access and runtime enforcement are configured independently.
Effective entitlement_required | Needs explicit entitlement allow? | Can gate policy/bundle still limit usage? |
|---|---|---|
false | No | Yes |
true | Yes | Yes |
Runtime hints you should honor
| Hint type | Meaning | Recommended client behavior |
|---|---|---|
rate.limit | request exceeds a rate window | backoff and retry with jitter, or queue |
quota.remaining | quota cannot cover the requested quantity | reduce quantity or split work |
budget.shortfall | selected budget cannot cover settlement | prompt top-up or choose a different budget |
funding.xusd_shortfall | account funding is insufficient | prompt top-up, degrade, or deny based on policy |
Packaging checklist
- Entitlements reflect product access boundaries.
- Gate bundle mapping is deterministic for each account.
- Customer-facing behavior for
rate.limitand shortfall hints is defined in product UX.
Next
- Gate bundle mapping: Gate policies and bundles
- Runtime semantics: Gate runtime