Limits and error codes
In short
- Every size limit, timer and price setting in the code.
- Money in requests is whole nano-USD as a string.
- There is no request rate limiter.
Petrova is not live. Every number here is a constant or setting in the current code. File names are given so each one can be checked.
Limits
Requests
| Limit | Value | Where |
|---|---|---|
Body size, /v1/messages, /v1/chat/completions, /v1/responses | 32 MiB | apps/api/src/messages.ts |
| Body size, repo index | 16 MiB | apps/api/src/memory.ts |
| Body size, missing-blobs check | 4 MiB | apps/api/src/memory.ts |
| Body size, every other route | 64 KiB | apps/api/src/app.ts |
| Time to upload a request body | 15 s | apps/api/src/app.ts |
| Time to answer | No limit on gateway routes (socket timeout turned off per call) | apps/api/src/messages.ts |
max_tokens | 1 to 1,000,000 | apps/api/src/messages.ts |
max_tokens when an OpenAI-format request leaves it out | 32,000 (used to size the hold) | apps/api/src/translate.ts |
| Request rate | No rate limiter. Only spend caps, supplier capacity and loop pause slow you down | — |
Keys and ids
| Limit | Value | Where |
|---|---|---|
| API key | ptrv_test_ + 43 characters (32 random bytes). Stored as SHA-256 | apps/api/src/auth.ts |
| Agent, parent agent and session ids | [A-Za-z0-9_:.-], 1–128 characters. A malformed id is refused, not dropped | packages/billing/src/budgets.ts |
| Idempotency key on holds | [\w:.-], 1–128 characters | packages/billing/src/quotes.ts |
| Key scopes | balance:read, catalog:read, quote:write, budget:write, seller:write, memory:read, memory:write, cloud:write, payout:write, plan:write, referral:write. operator:settle exists for Petrova's operator only; no customer key can have it | apps/api/src/auth.ts |
| How to send the key | Authorization: Bearer ptrv_test_... on every route. The model gateway routes (/v1/messages, /v1/messages/count_tokens, /v1/chat/completions, /v1/responses) also take x-api-key or x-petrova-key | apps/api/src/auth.ts (presentedKey), apps/api/src/messages.ts |
Billing
| Limit | Value | Where |
|---|---|---|
| Fee on a tool call | None: the tool's own price (TOOL_FEE_BPS = 0) | packages/billing/src/settlement.ts |
| Fee on adding money | 2% from a chain (USDG, USDC), 4% by card (not connected), shown as an amount before paying, rounded up once | packages/billing/src/add-fee.ts |
| Fee on a model call (not on sale) | 5.5%, rounded up once (feeNusd) | packages/billing/src/settlement.ts |
| Quote life | 120 s by default, 1–3,600 s allowed. Gateway quotes: 60 s | packages/billing/src/quotes.ts, apps/api/src/messages.ts |
| Hold size for a model call | Input bound (body bytes ÷ 3, rounded up) at the highest input-side price, plus max_tokens at the output price, plus the fee | apps/api/src/messages.ts |
| Crash cleanup | Holds older than 900 s whose lease ran out (60–86,400 s). On by default every 60 s (5–3,600 s); PETROVA_SWEEP_INTERVAL_SECONDS=0 turns it off | packages/billing/src/sweeper.ts, apps/api/src/config.ts |
| Call lease | 900 s, renewed every 300 s while the call runs | apps/api/src/messages.ts |
| Session sticks to one supplier | 1 hour | apps/api/src/messages.ts |
| Loop check | Last 20 tool calls. Same call 3 times: warn. 5 times: pause. A-B-A-B: warn at 4, pause at 8 | packages/optimization/src/loops.ts |
| Money values | Whole nano-USD, 0 to 2^63−1 | packages/billing/src/money.ts |
Money in requests
Every amount you send is a string of whole nano-USD (1 USD = "1000000000"). Decimals are refused.
| Request | Field | Example |
|---|---|---|
POST /v1/budgets (set a cap) | body { "scope", "ref", "limit_nusd" } | {"scope":"agent","ref":"research-bot","limit_nusd":"5000000000"} is a $5 cap |
GET /v1/topups/quote (top-up preview) | query amount_nusd | ?amount_nusd=500000000000 previews a $500 top-up |
GET /v1/tools | query max_price_nusd | ?max_price_nusd=10000000 is $0.01 or less per call |
POST /v1/tools/{id}/call | body max_cost_nusd | "10550000" is at most $0.01055, fee included |
POST /v1/earnings/withdraw | body amount_nusd, whole micro-USD | "10000000000" is $10 |
A wrong field name (for example amount_usd) is refused with a bare "Invalid request" today.
Tools and agents
| Limit | Value | Where |
|---|---|---|
| Highest tool price | $50 per call | packages/tools/src/importer.ts |
| Tool answer size | 1 MiB; timeout 15 s | packages/tools/src/pay.ts |
| A tool provider is hidden when | Absorbed losses are above 2% of call value | packages/tools/src/store.ts |
| Listing price | Above $0, at most $50 | packages/tools/src/listings.ts |
| Seller fee | 7.5% by default; setting 5–10% | packages/billing/src/earnings.ts |
| Pay-later limit | The lower of $500 and 30% of the last 7 days of income from other accounts | packages/billing/src/earnings.ts |
| Payout hold-back | 7 days; setting 0–90 | packages/billing/src/earnings.ts |
| Payout amount | Whole micro-USD (USDC has 6 decimals). Others are refused, not rounded | packages/billing/src/payouts.ts |
| Customer AWS fee | 5% of list price above the first $3,000 of list spend each UTC month | packages/billing/src/fee-plans.ts |
| Seller re-check | 2% of eligible (temperature 0) calls, stream and non-stream; on by default when a non-direct supplier is configured; pass at 70% similarity; tool calls must match exactly | apps/api/src/seller-checks.ts, apps/api/src/messages.ts |
| Reseller fee | 25% of the saving against list, at most 6% of what you pay; never above list | packages/billing/src/resale.ts |
| Local usage estimate | 4 bytes per token, only when a supplier gives no usable usage | apps/api/src/messages.ts (localTokens) |
Sign-up, links and live mode
| Limit | Value | Where |
|---|---|---|
| Sign-ups | 5 an hour from one address, 200 an hour from everyone | packages/billing/src/agent-start.ts |
| An account nobody funds | Expires after 72 hours | packages/billing/src/agent-start.ts |
| A person's link | Works once, for 30 minutes | packages/billing/src/person-links.ts |
| Link code | 6 digits on fund and approve links (none on top-ups); 5 wrong tries close the link | packages/billing/src/person-links.ts |
| Default maximum per agent call | $1.00 | apps/api/src/agent.ts |
| Live tools, per call | At most $1 in code; starting setting $0.10 | apps/api/src/live-tools.ts, .env.production.example |
| Live tools, per day | At most $50 in code; starting setting $5 | apps/api/src/live-tools.ts, .env.production.example |
| Live readiness report | Good for 24 hours, for one commit | apps/api/src/live-spend.ts |
Memory and chain.watch
| Limit | Value | Where |
|---|---|---|
| Injected memory block | 1,500 tokens (1,200 repo map, 300 saved memories) | packages/memory/src/block.ts |
| Repo context answer | 2,000 tokens | packages/memory/src/index-commit.ts |
| Files per commit / file size | 50,000 / 256 KiB | packages/memory/src/index-commit.ts |
| Saved memory | 1–1,000 characters; recall returns at most 10 | packages/memory/src/memories.ts |
| chain.watch price | $0.00005 per event by default (setting must be above $0.000011) | packages/tools/src/chain/pricing.ts |
| chain.watch hold | 100 events by default (1–1,000); an open hold settles after 60 s | packages/tools/src/chain/pricing.ts, watch.ts |
Error codes
Petrova answers in three shapes. Each route uses the shape its clients expect.
Claude format (/v1/messages)
Body: { "type": "error", "error": { "type": ..., "message": ... } }.
| Status | error.type | When | Retry? | Test |
|---|---|---|---|---|
| 400 | invalid_request_error | Bad JSON, no model, bad max_tokens, model not in the catalog, malformed agent or session id | No | tests/unit/messages.test.ts |
| 401 | authentication_error | No key or a bad key | No | "auth accepts x-api-key or a bearer token and rejects anything else" |
| 403 | permission_error | Key lacks quote:write (or memory:read for x-petrova-repo) | No | tests/integration/memory.test.ts |
| 402 | billing_error | Not enough balance. x-should-retry: false | No | errors.test.ts, "no balance on /v1/messages is a Claude-shape billing_error, not retried; on OpenAI routes it is insufficient_quota" |
| 409 | invalid_request_error | The same request id was already used | No | "billing gates the call: no balance means no upstream call, and a reused request id is refused" |
| 413 | request_too_large | Body over 32 MiB. x-should-retry: false | No | errors.test.ts, "a body that is too large comes back in each route's own shape" |
| 429 | rate_limit_error | A spend cap was reached. x-should-retry: false | No | "an agent over its cap gets the clean spend-limit 429 and nothing is held" |
| 429 | rate_limit_error | Loop pause. x-petrova-loop: pause, x-should-retry: false | No | "a repeating tool loop is paused before it is paid for again" |
| 502 | api_error | No supplier could be reached | Yes | "when every upstream fails the hold is released and the last error is returned" |
| 529 | overloaded_error | Every supplier's capacity for the day is used. x-should-retry: false | No | tests/integration/capacity.test.ts |
| 429/529/500 | as the supplier sent it | A supplier failed before the first word. Petrova tried the next one first | Yes | "a 529 from the first upstream fails over to the next, stream and non-stream" |
OpenAI format (/v1/chat/completions, /v1/responses)
Body: { "error": { "message", "type", "param": null, "code" } }. Codex stops on insufficient_quota.
| Status | code | When |
|---|---|---|
| 400 | invalid_request | Bad request; n other than 1; previous_response_id (not supported) |
| 401 | invalid_api_key | No key or a bad key |
| 403 | permission_denied | Missing scope, or account not available |
| 409 | request_id_reused | The same request id was already used |
| 429 | spend_limit_reached (type insufficient_quota) | A spend cap was reached |
| 413 | request_too_large | Body over 32 MiB |
| 429 | insufficient_quota | Not enough balance (x-should-retry: false) |
| 429 | loop_paused | Loop pause |
| 503 | server_is_overloaded | Supplier overloaded (a 529 becomes 503) |
Tests: tests/integration/openai.test.ts and tests/unit/openai.test.ts.
Petrova format (every other /v1/* route)
Body: { "error": { "code", "message", "request_id" } }.
| Status | Codes |
|---|---|
| 400 | invalid_request, invalid_quote, payload_mismatch, invalid_settlement, invalid_budget, invalid_inputs, invalid_listing, invalid_rules, invalid_withdrawal, invalid_role, external_id_mismatch, invalid_filter, tool_not_callable, invalid_funding, invalid_owner |
| 401 | unauthorized |
| 402 | insufficient_balance, budget_exceeded, over_max_cost, insufficient_withdrawable |
| 403 | scope_denied (also: settlement without operator:settle), account_unavailable, live_tools_disabled, self_dealing |
| 404 | not_found, quote_not_found, reservation_not_found, receipt_not_found, tool_not_found, agent_not_found, cloud_not_found, watch_not_found, repo_not_found, commit_not_found, memory_not_found |
| 409 | quote_expired, quote_already_used, idempotency_conflict, reservation_not_held, reservation_unavailable, price_changed, payto_changed, duplicate_call, listing_conflict, payout_destination_missing, cloud_not_connected, manifest_conflict, parent_not_indexed, index_in_progress, balance_limit, owner_conflict |
| 413 | request_too_large (body over the route's limit; 64 KiB on most routes) |
| 500 | internal_error |
| 502 | challenge_invalid, tool_unreachable, signer_failed, index_failed |
| 503 | cloud_unavailable, capacity_exhausted |
Map: HTTP_STATUS in apps/api/src/app.ts (wallet, plan and referral codes are there too). Tests: tests/integration/http.test.ts, "HTTP maps billing failures onto the right status codes"; tests/integration/errors.test.ts, "every billing error code maps to its HTTP status, including the five that fell back to 400" (every code in the map, through the real error handler).
chain.watch streams end with a Claude-format error event: rate_limit_error for a cap, billing_error for no balance.
Known mismatches
Fixed since the last check: no balance on /v1/messages is now a Claude-shape 402 billing_error; a body over 32 MiB is 413 request_too_large in each route's own shape; capacity_exhausted, balance_limit, invalid_funding, invalid_owner and owner_conflict are now in the status map.
Still open:
- A Petrova-format validation error says only "Invalid request". It does not name the field that was wrong (
apps/api/src/app.ts). - These codes exist in code but no test checks them by name:
invalid_quote,tool_not_callable,tool_unreachable,signer_failed,listing_conflict,agent_not_found,invalid_rules,invalid_withdrawal,payout_destination_missing,cloud_unavailable,invalid_role,cloud_not_found,cloud_not_connected,commit_not_indexed,blob_too_large,index_in_progress,repo_not_found,memory_not_found,account_unavailable, and the 413.
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.