Reservation headroom

A safety buffer that leaves room for the unknown output cost of an LLM call. When a limit group has headroom configured, reserve() blocks before the true cap is reached - so the cap isn't breached by a large reply.

Why headroom exists

When you meter LLM tokens or dollar cost, you know the inputcost before calling the model, but you don't know the output cost until the response arrives. A naive flow - reserve(inputCost), call the LLM, commit(outputCost) - can push the counter well past the quota if the reply is large. Multiply by concurrent users and you get systematic overshoot.

Headroom solves this by treating part of the remaining quota as “reserved for output.” Reserves are blocked once usage crosses the gate, leaving enough room for the commit topup that follows.

Two configurations

Both are set per limit group in the plan builder's Reservation safety collapsible. They share the same LimitGroupHeadroom shape:

headroom?: {
  thresholdPct?: number;      // 1..100 - block at quota × pct/100
  outputMultiplier?: number;  // > 0   - block when current + input × (1+mult) > quota
}

Percent threshold (coarse)

Block new reserves once usage reaches a percentage of the quota. Good when you don't know the typical input-to-output ratio for your users:

// Block at 85% of a 100k token cap.
// Gate = 100_000 × 0.85 = 85_000 tokens.
headroom: { thresholdPct: 85 }

Output multiplier (precise)

Block when current + inputTokens × (1 + multiplier) would exceed the quota. Use when you know the typical output-to-input ratio - for example, a chain-of-thought model that reliably generates 3× the input length:

// Block when the expected total (input + 3× output) would exceed quota.
headroom: { outputMultiplier: 3 }

When both fields are set, outputMultiplier takes precedence. Percent is the simpler, safer default for plans without a known ratio.

Configured per limit group

Headroom lives on the plan, not in the SDK call. Set it in the dashboard plan builder on any LLM row under Reservation safety. The setting persists in LimitGroup.headroom on the plan object. You do not pass anything extra in your reserve() or canUse() calls - the server applies the buffer automatically.

Headroom is not credit-coverable

Credits extend capacity past the true plan quota. The safety buffer, however, exists to prevent overshoot from unknown output cost - that is a different concern. Even if the user has credit packs, a headroom block stands. The correct CTA when reasons includes reservation_headroom_exceededis “wait until the next period resets” or “upgrade to a higher cap,” not “buy more credits.”

What happens at runtime

On every reserve() call, the server computes a projected usage and compares it to the gate:

• Percent mode: gate = quota × thresholdPct / 100. Block when current + inputTokens > gate.
• Multiplier mode: gate = quota. Block when current + inputTokens × (1 + outputMultiplier) > gate.

When blocked, reserve() returns { allowed: false, reasons: ['reservation_headroom_exceeded'] }. No counters are incremented. The groups[i].headroomGate field on the response shows the effective gate value so your UI can display how close the user is.

Commits are allowed to overshoot the quota. Once the AI call returns, commit() records the actual cost truthfully - even if that pushes the counter past quota. The response's groups[i].overflow flag signals this. The next reserve() will block on limit_reached.

Example: 100k token cap at 85%

Plan: 100,000 tokens/month, thresholdPct: 85 → gate = 85,000.

// Current usage: 80,000 tokens (80% of cap).
// Reserve with 10,000 input tokens → projected: 80,000 + 10,000 = 90,000.
// 90,000 > 85,000 (gate) → BLOCKED.

const r = await vevee.reserve(userId, 'llm.gpt-4o', 0, undefined, {
  inputTokens: 10_000,
});

// r.allowed = false
// r.reasons = ['reservation_headroom_exceeded']
// r.groups[0].current     = 80_000
// r.groups[0].quota       = 100_000
// r.groups[0].headroomGate = 85_000

// The user has consumed 80% of their cap.
// The buffer has reserved the last 15% for unknown output cost.
// Correct response: show a near-limit warning, not an upgrade wall.