# Spending limits

Understand reservations, capped charges, and user-controlled premium access.

Users control how much each application may spend. New application premium
limits start at zero, so users must permit premium spending during consent or
on their Enlitt application settings page. Your server cannot raise their limits.

## What happens to a premium maximum

1. You declare `maxCharge` in NANOUSD before the provider runs.
2. Enlitt checks the user's session, credits, and applicable limits.
3. A nonzero per-call limit below your maximum lowers the effective maximum.
4. Enlitt reserves capacity before admitting the call.
5. On completion or cancellation, the actual charge is capped at that effective maximum.
   Unused reserved capacity is released. Failed calls charge zero.

For example, you might declare a $0.01 maximum and compute a $0.008 price.
If Enlitt returns an effective maximum of $0.005, the final charge is $0.005.
Exceeding a nonzero per-call limit does **not** by itself refuse the call.
Choose pricing that still makes sense when the effective maximum is lower.

A `premium_per_call` limit of zero blocks premium calls. Standard access has
its own credit and rate constraints; a zero premium limit does not disable it.

## Limits and credits are different refusals

`EnlittLimitExceededError` uses code `spending_limit_exceeded`. Its `limitRule`
identifies the rule, such as `premium_per_call`, `standard_per_call`,
`rate.standard`, or `rate.premium`, without exposing its value.

`EnlittInsufficientCreditsError` uses `premium_balance_exhausted` or
`standard_balance_exhausted`. A premium refusal may include
`admissibleMaxChargeNanoUsd`, the smaller maximum currently affordable.
Your application may choose a lower maximum for a new call; the SDK does not
make that business decision automatically. Failed admission never invokes
your premium provider.

When supplied, `authorizeUrl` points to Enlitt's screen where the user can
change settings or obtain credits. Give the user an appropriate explanation
and a link; see [Errors and recovery](/docs/errors.md).

## The limits object

`limits` includes the user-settable `premium_per_call` and a read-only
`rate` tuple: `{ standard, premium, period_minutes }`. The tuple bounds
captured plus reserved credits for this application and user in each fixed
window. Enlitt chooses it; neither the user nor the business edits it in v1.
It is separate from request-per-minute throttling.

The SDK's [`usage()`](/docs/usage.md) returns an advisory remaining percentage and
NANOUSD call cap, not the limits object or the user's account balance.