Limits and error codes

Fixture onlyChecked 16 November 2026

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

LimitValueWhere
Body size, /v1/messages, /v1/chat/completions, /v1/responses32 MiBapps/api/src/messages.ts
Body size, repo index16 MiBapps/api/src/memory.ts
Body size, missing-blobs check4 MiBapps/api/src/memory.ts
Body size, every other route64 KiBapps/api/src/app.ts
Time to upload a request body15 sapps/api/src/app.ts
Time to answerNo limit on gateway routes (socket timeout turned off per call)apps/api/src/messages.ts
max_tokens1 to 1,000,000apps/api/src/messages.ts
max_tokens when an OpenAI-format request leaves it out32,000 (used to size the hold)apps/api/src/translate.ts
Request rateNo rate limiter. Only spend caps, supplier capacity and loop pause slow you down—

Keys and ids

LimitValueWhere
API keyptrv_test_ + 43 characters (32 random bytes). Stored as SHA-256apps/api/src/auth.ts
Agent, parent agent and session ids[A-Za-z0-9_:.-], 1–128 characters. A malformed id is refused, not droppedpackages/billing/src/budgets.ts
Idempotency key on holds[\w:.-], 1–128 characterspackages/billing/src/quotes.ts
Key scopesbalance: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 itapps/api/src/auth.ts
How to send the keyAuthorization: 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-keyapps/api/src/auth.ts (presentedKey), apps/api/src/messages.ts

Billing

LimitValueWhere
Fee on a tool callNone: the tool's own price (TOOL_FEE_BPS = 0)packages/billing/src/settlement.ts
Fee on adding money2% from a chain (USDG, USDC), 4% by card (not connected), shown as an amount before paying, rounded up oncepackages/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 life120 s by default, 1–3,600 s allowed. Gateway quotes: 60 spackages/billing/src/quotes.ts, apps/api/src/messages.ts
Hold size for a model callInput bound (body bytes ÷ 3, rounded up) at the highest input-side price, plus max_tokens at the output price, plus the feeapps/api/src/messages.ts
Crash cleanupHolds 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 offpackages/billing/src/sweeper.ts, apps/api/src/config.ts
Call lease900 s, renewed every 300 s while the call runsapps/api/src/messages.ts
Session sticks to one supplier1 hourapps/api/src/messages.ts
Loop checkLast 20 tool calls. Same call 3 times: warn. 5 times: pause. A-B-A-B: warn at 4, pause at 8packages/optimization/src/loops.ts
Money valuesWhole nano-USD, 0 to 2^63−1packages/billing/src/money.ts

Money in requests

Every amount you send is a string of whole nano-USD (1 USD = "1000000000"). Decimals are refused.

RequestFieldExample
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/toolsquery max_price_nusd?max_price_nusd=10000000 is $0.01 or less per call
POST /v1/tools/{id}/callbody max_cost_nusd"10550000" is at most $0.01055, fee included
POST /v1/earnings/withdrawbody 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

LimitValueWhere
Highest tool price$50 per callpackages/tools/src/importer.ts
Tool answer size1 MiB; timeout 15 spackages/tools/src/pay.ts
A tool provider is hidden whenAbsorbed losses are above 2% of call valuepackages/tools/src/store.ts
Listing priceAbove $0, at most $50packages/tools/src/listings.ts
Seller fee7.5% by default; setting 5–10%packages/billing/src/earnings.ts
Pay-later limitThe lower of $500 and 30% of the last 7 days of income from other accountspackages/billing/src/earnings.ts
Payout hold-back7 days; setting 0–90packages/billing/src/earnings.ts
Payout amountWhole micro-USD (USDC has 6 decimals). Others are refused, not roundedpackages/billing/src/payouts.ts
Customer AWS fee5% of list price above the first $3,000 of list spend each UTC monthpackages/billing/src/fee-plans.ts
Seller re-check2% 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 exactlyapps/api/src/seller-checks.ts, apps/api/src/messages.ts
Reseller fee25% of the saving against list, at most 6% of what you pay; never above listpackages/billing/src/resale.ts
Local usage estimate4 bytes per token, only when a supplier gives no usable usageapps/api/src/messages.ts (localTokens)
LimitValueWhere
Sign-ups5 an hour from one address, 200 an hour from everyonepackages/billing/src/agent-start.ts
An account nobody fundsExpires after 72 hourspackages/billing/src/agent-start.ts
A person's linkWorks once, for 30 minutespackages/billing/src/person-links.ts
Link code6 digits on fund and approve links (none on top-ups); 5 wrong tries close the linkpackages/billing/src/person-links.ts
Default maximum per agent call$1.00apps/api/src/agent.ts
Live tools, per callAt most $1 in code; starting setting $0.10apps/api/src/live-tools.ts, .env.production.example
Live tools, per dayAt most $50 in code; starting setting $5apps/api/src/live-tools.ts, .env.production.example
Live readiness reportGood for 24 hours, for one commitapps/api/src/live-spend.ts

Memory and chain.watch

LimitValueWhere
Injected memory block1,500 tokens (1,200 repo map, 300 saved memories)packages/memory/src/block.ts
Repo context answer2,000 tokenspackages/memory/src/index-commit.ts
Files per commit / file size50,000 / 256 KiBpackages/memory/src/index-commit.ts
Saved memory1–1,000 characters; recall returns at most 10packages/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 hold100 events by default (1–1,000); an open hold settles after 60 spackages/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": ... } }.

Statuserror.typeWhenRetry?Test
400invalid_request_errorBad JSON, no model, bad max_tokens, model not in the catalog, malformed agent or session idNotests/unit/messages.test.ts
401authentication_errorNo key or a bad keyNo"auth accepts x-api-key or a bearer token and rejects anything else"
403permission_errorKey lacks quote:write (or memory:read for x-petrova-repo)Notests/integration/memory.test.ts
402billing_errorNot enough balance. x-should-retry: falseNoerrors.test.ts, "no balance on /v1/messages is a Claude-shape billing_error, not retried; on OpenAI routes it is insufficient_quota"
409invalid_request_errorThe same request id was already usedNo"billing gates the call: no balance means no upstream call, and a reused request id is refused"
413request_too_largeBody over 32 MiB. x-should-retry: falseNoerrors.test.ts, "a body that is too large comes back in each route's own shape"
429rate_limit_errorA spend cap was reached. x-should-retry: falseNo"an agent over its cap gets the clean spend-limit 429 and nothing is held"
429rate_limit_errorLoop pause. x-petrova-loop: pause, x-should-retry: falseNo"a repeating tool loop is paused before it is paid for again"
502api_errorNo supplier could be reachedYes"when every upstream fails the hold is released and the last error is returned"
529overloaded_errorEvery supplier's capacity for the day is used. x-should-retry: falseNotests/integration/capacity.test.ts
429/529/500as the supplier sent itA supplier failed before the first word. Petrova tried the next one firstYes"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.

StatuscodeWhen
400invalid_requestBad request; n other than 1; previous_response_id (not supported)
401invalid_api_keyNo key or a bad key
403permission_deniedMissing scope, or account not available
409request_id_reusedThe same request id was already used
429spend_limit_reached (type insufficient_quota)A spend cap was reached
413request_too_largeBody over 32 MiB
429insufficient_quotaNot enough balance (x-should-retry: false)
429loop_pausedLoop pause
503server_is_overloadedSupplier 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" } }.

StatusCodes
400invalid_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
401unauthorized
402insufficient_balance, budget_exceeded, over_max_cost, insufficient_withdrawable
403scope_denied (also: settlement without operator:settle), account_unavailable, live_tools_disabled, self_dealing
404not_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
409quote_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
413request_too_large (body over the route's limit; 64 KiB on most routes)
500internal_error
502challenge_invalid, tool_unreachable, signer_failed, index_failed
503cloud_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.