# Rate limits and spend caps

Apply windowed controls on supported paths and understand identity and concurrency limits.

Updated: 2026-09-22

Canonical: https://docs.kastra.ai/evidence/limits

## Select the right control

Rate-limit effects require Pro-or-higher authoring access. Spend-cap effects require Team-or-higher and a supported proxy metering path. Confirm actual workspace entitlements before rollout.

Define the metric, scope, threshold, time window, and on-exceed behavior in the console. Usage-limit management is under `/api/v1/usage/limits`; writes require an administrator. The response includes scope-strength information so a label-based scope is not confused with a server-bound identity.

## Identity matters

A principal/customer limit is only as strong as the identity binding that supplies it. Client-chosen labels can be changed by the caller. Prefer credential-bound context where the control must resist a caller changing its identifier.

## Spend timing

When an accumulated proxy cap is already reached, a subsequent request can be rejected before forwarding. The request that crosses the threshold and already-running concurrent requests can still accrue usage. Windowed metering is not a promise of zero overshoot or an exact provider invoice ceiling.

## Rate-limit response negotiation

The evaluation API uses `Accept-Kastra-RateLimit: 1` to opt into supported `429` responses. Older hook clients handle denial through their expected `403` path. Decode the structured decision instead of treating a rate-limit response as permission to retry unrestricted.

## Verify the full policy

Use small test thresholds and harmless requests. Check combined rules: a metered rule below its limit must not suppress a later block. Inspect actual counters and decisions. Billing-driven observe-only can withhold enforcement; spend caps do not override that posture.