Skip to main content
Budget rules cap spend for a customer or pooled account over a daily, weekly, or monthly period.

​
Enforcement modes

ModeBehavior
WarnThe provider call proceeds. Pylva records and alerts when spend crosses the limit.
Hard stopThe SDK throws before the provider call, so the provider is not billed.

​
TypeScript handling

import { init, PylvaBudgetExceeded } from "@pylva/sdk";

init({ apiKey: process.env.PYLVA_API_KEY! });

try {
  return await openai.chat.completions.create({ model, messages });
} catch (err) {
  if (err instanceof PylvaBudgetExceeded) {
    return cachedOrSmallerResponse();
  }
  throw err;
}

​
Python handling

from pylva import PylvaBudgetExceeded

try:
    response = openai_client.chat.completions.create(...)
except PylvaBudgetExceeded:
    response = cached_or_smaller_response()

​
How the SDK stays current

The SDK keeps a local accumulator for active budget rules so it can make a fast pre-call decision. Pylva then reconciles that local view with backend totals. Backend totals are authoritative. If pricing data is unavailable or the backend cannot be reached, the SDK passes through rather than blocking the host application because of a Pylva outage. When a hard stop fires, return a product-specific fallback:
  • Cached answer.
  • Smaller model path.
  • Queued job.
  • “Try again later” response.
  • Human handoff.
Avoid retry loops that immediately reissue the same expensive call.