Fails silently
In short
- Problems that give no error, and how to check for each one.
- Most start with: does the answer have an x-petrova-receipt header?
- Today every answer is a test answer.
Petrova is not live. This page describes the code in this repository, on test fixtures.
Most problems give you an error. These do not. Each one looks fine until you check. Here is what to check.
Your calls never reach Petrova
What happens. The base URL was set in another shell or config file. Your tool keeps calling its old provider, and everything still works.
How to check. Every answer from Petrova has an x-petrova-receipt header, and each call adds a line to GET /v1/receipts. No header and no new receipt means the call went somewhere else.
The base URL has the wrong ending
What happens. Claude Code and the Anthropic SDK want the URL without /v1. The OpenAI SDK and Codex want it with /v1. A wrong ending may give a 404, but some tools hide that and retry or fall back.
How to check. See getting started, then look for a receipt.
Agent and session caps do not apply
What happens. Those caps count only calls that name an agent or session. Claude Code sends the right headers by itself. Anything else (the Anthropic SDK, Cline, Aider, your own agent) must send x-petrova-agent-id and x-petrova-session-id, or the agent and session caps do not apply. Key, project and account caps always apply.
How to check. Open a receipt. If it names no agent and no session, those caps are not counting this call. More in billing.
A huge max_tokens makes a huge hold
What happens. The hold is the most a call could cost. A big max_tokens means a big hold, even if the call ends up cheap. While it runs, that money counts against your caps and your available balance, so other calls may be refused. If the hold itself does not fit, Petrova lowers max_tokens to fit, which can cut a long answer short.
How to check. Look for an x-petrova-max-tokens header: it means the value was lowered. Compare held and charged on a receipt. If they are far apart on every call, lower max_tokens.
Repo memory is not on
What happens. Repo memory only runs when a call sends x-petrova-repo: name@sha. Without it, nothing is added and nothing complains.
How to check. The answer has an x-petrova-memory-tokens header when memory was added.
A loop warning is only a header
What happens. At 3 repeats of the same tool call, Petrova sends x-petrova-loop: warn, and the call still runs and is charged. The pause comes at 5 repeats. If nothing reads the header, you only find out at the pause.
How to check. Log x-petrova-loop in your client. More in billing.
The cost on a receipt is an estimate
What happens. If a supplier sends no usable usage, Petrova estimates the tokens from the bytes. The estimate can be high or low. If it is high, a later invoice gives the difference back. If it is low, Petrova pays the difference.
How to check. Read cost_basis on the receipt: reported, estimated or input_only. Today invoices come from a file, so a true-up does not happen until one is loaded.
Test answers look like real answers
What happens. Today every model answer is canned by a fixture. It looks like a real answer, and it has a real-looking receipt.
How to check. GET /v1/balance says "mode": "fixture". Do not treat any of these answers or costs as a real result.
What we tested
This page is a list of known behaviours, written from the code and the docs. The behaviours above have tests, named on their own pages. We have not tested what third-party tools do with a wrong base URL.
Last checked against the code: 16 November 2026. Something wrong? The source of this page is in the repository, so a fix is one edit.