Skip to content

Troubleshooting

  • Use Python 3.10+.
  • Prefer pip install "kazenai-finops[openai]==1.2.6" (or [anthropic] / [providers]) so the supported provider SDK range is installed.
  • If versions disagree across README, PyPI, and runtime __version__, trust the installed wheel metadata and file a docs bug.
  • Confirm max_budget_usd (or the shared SharedBudget) is large enough for the estimated maximum exposure of the next call, not just its typical cost.
  • Several clients each with max_budget_usd have separate caps; use one SharedBudget when they belong to one workflow.
  • Calls refused with BudgetUnavailable while Agent FinOps is unreachable are the default (fail-closed). An admin can switch the organization to fail-open; see When Agent FinOps is unreachable.
  • Offline denial proof: Control demo.
  • Budget still looks used after a serverless function returned: the settle was queued in the background (1.2.4 and later) and the process was frozen before it was sent. Call kazenai.spine.guard.drain_settlements() before returning; see Latency.

The model has no price in the pricing table, so its spend cannot be bounded and the call is blocked before dispatch. Pin a priced model, add the price with KAZENAI_PRICING_JSON, or opt in to KAZENAI_UNKNOWN_MODEL_POLICY=estimate. See Configuration.

The call used a surface Control does not guard, such as OpenAI Realtime, legacy client.completions, or Anthropic beta Messages (client.beta.messages, including LangChain ChatAnthropic(betas=...)), or a Responses request whose cost cannot be bounded before the call: background=True, previous_response_id / conversation / stored prompt, or a built-in tool. The exception’s error_code names the reason. Use Chat Completions, responses.create with function tools and input items, or client.messages.

Raised only with monitor(..., loop_guard="block"). The request repeated one of the same customer’s last requests on that client (or, with no customer ID, one of the client’s calls without one) closely enough to look like a loop, so it was refused before dispatch, and the run’s timeline has a finops.loop.anomaly event with "action": "blocked". Drop loop_guard="block" to record repeats and send them (the default), or pass loop_guard="off". On 1.2.2 and earlier, blocking was the default: upgrade kazenai to 1.2.3 or later (1.2.5 is current). See Repeated requests.

Use only the surfaces marked SUPPORTED in the supported-surface matrix. A normal stream with authoritative final usage settles exactly. Early cancellation, provider failure, or a stream without final usage remains financially pending rather than being recorded as an exact zero.

stream_cutoff_usd is an optional local guard based on output observed by the client. It cannot see hidden reasoning or guarantee that the provider stopped generating or billing immediately after the client closed the stream.

File a documentation issue in the public kazenai-core issue tracker or in the affected package repository. The documentation source repository is intentionally private; docs.kazenai.com is the canonical public surface.