Skip to content

Errors

Error When it is raised
BudgetExceeded Hard deny before provider dispatch: a local or shared limit has no room, the organization is paused in Agent FinOps, or a tier-mismatch breaker is open for that organization, provider and model (FinOps HTTP 409 tier_breaker). From 1.2.6, an over-limit refusal says what the call could cost and what was left; a lower max_tokens lowers what a call can cost (see Reservation)
InvalidAttribution Agent FinOps didn’t accept the call’s customer or feature ID (invalid_attribution), for example one with a space in it. The message carries the reason. The call never runs, whatever the fail-open setting. A subclass of BudgetUnavailable, so existing handlers catch it; kazenai and kazenai-finops 1.2.6 and later (earlier releases raised BudgetUnavailable: Pre-call reservation HTTP 400). See which IDs are accepted
BudgetUnavailable No usable answer from Agent FinOps: it could not be reached, timed out, or answered with an error status, and the organization uses fail-closed (the default; see When Agent FinOps is unreachable). Also raised when Agent FinOps rejects the API key, whatever the setting, and when it refuses the reservation with HTTP 403 because monitor() names a different organization or workspace than the key belongs to (pass the key’s org_id and workspace_id; see Connect hosted limits)
PricingConfigError Pricing configuration is invalid. Under Control, monitor() raises it at setup when KAZENAI_TIER_MISMATCH_MULTIPLIER is missing, not a number, or below 1 (see Configuration)
UnsupportedModeError The request cannot be bounded before dispatch, so it is refused. error_code says why, for example unsupported_provider_retries (build the client with max_retries=0), unguarded_dispatch (a paid endpoint outside Control; see allow_unmetered), responses_background_unsupported, responses_builtin_tool_unsupported, service_tier_unsupported. For a model with a long-context price band (GPT-5.4 and later, GPT-6, Claude Haiku 5.5): long_context_chat_unsupported (a Chat Completions request with images or audio, or one that could reach the long-context threshold; use the Responses API), input_counter_unavailable (the client has no exact input counter; OpenAI Responses needs openai 2.x), input_counter_failed (the provider’s free count request failed, for example an invalid key)
AttributionConflict Two different values for the same attribution field on one call, for example a customer ID from use_attribution(...) and another from monitor(..., business_subject_ref=...). Raised before dispatch (see Attribution)
CustomerIdRequired monitor(..., require_customer_id=True) and the call names no customer ID (business_subject_ref), for example in a ThreadPoolExecutor worker that didn’t get the copied context. Raised before dispatch; kazenai 1.2.1 and later (see Attribution)
KazenCircuitBreaker Soft trajectory pause after a completed call
KazenBudgetExceeded Deprecated alias of KazenCircuitBreaker (not the hard deny)
StreamCutoffError Optional local stream_cutoff_usd threshold reached; final financial outcome may remain pending
UnknownModelError The model has no price, so its spend cannot be bounded; blocked before dispatch in every environment by default (see Configuration)
LegacyBudgetEndpointUnsupported (kazenai_finops.spend) FinOpsSpendClient.check_budget() / reconcile_budget() reached hosted Agent FinOps, which refuses the legacy endpoints under Control (HTTP 501). Use monitor()

A hard deny means the provider was never called for that attempt. A deny from Agent FinOps also leaves a decision receipt that says which limit, pause or breaker refused the call.