Errors
In short
- Every error code, its HTTP status, and whether to retry.
- Model calls answer in Anthropic or OpenAI shape; other routes in Petrova shape.
- x-should-retry: false means fix something first.
Petrova is not live. These are the error codes the code in this repository returns today, checked on 5 November 2026 against HTTP_STATUS in apps/api/src/app.ts, the gateway in apps/api/src/messages.ts and the memory errors in packages/memory/src.
"Retry?" means: will the same request work if you send it again unchanged. "No" means fix something first (add funds, raise a cap, change the request).
Three shapes
Each route answers in the shape its clients expect.
| Routes | Shape |
|---|---|
/v1/messages, /v1/messages/count_tokens | Anthropic: { "type": "error", "error": { "type", "message" } } |
/v1/chat/completions, /v1/responses | OpenAI: { "error": { "message", "type", "param": null, "code" } } |
Every other /v1/* route | Petrova: { "error": { "code", "message", "request_id" } } |
When Petrova means "do not retry" it also sends x-should-retry: false, which Claude Code and the SDKs respect.
Model calls: Anthropic shape
| Status | error.type | When | Retry? | Test |
|---|---|---|---|---|
| 400 | invalid_request_error | Bad JSON, no model, bad max_tokens, a model not in the price table, a malformed agent or session id | No | tests/unit/messages.test.ts |
| 401 | authentication_error | No key, or a bad or revoked key | No | "auth accepts x-api-key or a bearer token and rejects anything else" |
| 402 | billing_error | Not enough balance (x-should-retry: false) | No: add funds | errors.test.ts, "no balance on /v1/messages is a Claude-shape billing_error, not retried; on OpenAI routes it is insufficient_quota" |
| 403 | permission_error | The key lacks quote:write (or memory:read when you send x-petrova-repo) | No | tests/integration/memory.test.ts |
| 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 would be crossed. Nothing was held (x-should-retry: false) | No: raise the cap | "an agent over its cap gets the clean spend-limit 429 and nothing is held" |
| 429 | rate_limit_error | Loop pause: the same tool call 5 times in the last 20 (x-petrova-loop: pause, x-should-retry: false). Nothing was held | No: fix the loop | "a repeating tool loop is paused before it is paid for again" |
| 502 | api_error | No supplier could be reached. The hold was released; you paid nothing | 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). You paid nothing | Later | tests/integration/capacity.test.ts |
| 429 / 500 / 529 | as the supplier sent it | A supplier failed before the first word and so did every other one | Yes | "a 529 from the first upstream fails over to the next, stream and non-stream" |
Model calls: OpenAI shape
| Status | code | When | Retry? |
|---|---|---|---|
| 400 | invalid_request | Bad request; n other than 1; previous_response_id (not supported) | No |
| 401 | invalid_api_key | No key or a bad key | No |
| 403 | permission_denied | Missing scope, or account not available | No |
| 409 | request_id_reused | The same request id was already used | No |
| 413 | request_too_large | Body over 32 MiB | No |
| 429 | insufficient_quota | Not enough balance (x-should-retry: false). Codex stops on this code | No |
| 429 | spend_limit_reached (type insufficient_quota) | A spend cap would be crossed | No |
| 429 | loop_paused | Loop pause | No |
| 503 | server_is_overloaded | Every supplier is overloaded (a 529 becomes 503) | Later |
Tests: tests/integration/openai.test.ts and tests/unit/openai.test.ts.
Everything else: Petrova shape
On the older routes a validation error says only "Invalid request" without naming the field. That is a known gap (status). The agent routes name the field, and answer in the one shape described in the agent's journey.
400: the request is wrong
| Code | What it means |
|---|---|
invalid_request | A field is missing or malformed. Also used for any code not in the status map |
invalid_quote, payload_mismatch | The quote does not match the payload you sent with it |
invalid_settlement | A settlement body is wrong (operator only) |
invalid_budget | A cap amount or reference is wrong, or the project or key is not in your account |
invalid_inputs, tool_not_callable | The tool inputs are wrong, or the tool is listed but cannot be called (MPP, another network, it needs a sign-in or the provider's own key) |
invalid_listing, invalid_rules, invalid_withdrawal | A listing, earning rule or withdrawal amount is wrong (withdrawals must be whole micro-USD) |
invalid_role, external_id_mismatch | The AWS role ARN or external id is wrong |
invalid_filter | A chain.watch filter is wrong |
invalid_funding, invalid_owner, invalid_wallet, invalid_topup, invalid_plan | Funding, owner, wallet, top-up or plan input is wrong |
blob_mismatch, blob_too_large, missing_blobs | A repo index upload is wrong or too big (256 KiB per file) |
401, 402, 403
| Status | Code | What it means | What to do |
|---|---|---|---|
| 401 | unauthorized | No valid key. Most routes take only Authorization: Bearer ptrv_test_... | Check the key and the header |
| 401 | invalid_signature | A wallet-signed message did not verify | Sign again |
| 402 | insufficient_balance | Not enough balance for the hold | Add funds |
| 402 | budget_exceeded | A cap would be crossed | Raise the cap or wait |
| 402 | over_max_cost | The tool costs more than your max_cost_nusd | Raise your max |
| 402 | per_call_limit | This call is above the card's per-call limit. It never waits | Ask for less, or have the owner raise the limit |
| 402 | approval_required | Above the card's approval line, on a route that cannot wait, such as a seller listing | Have the owner raise the line |
| 402 | insufficient_withdrawable | You asked to withdraw more than is withdrawable | Ask for less |
| 402 | not_funded | An agent wallet asked for a key before any top-up was credited | Top up first |
| 403 | scope_denied | The key cannot do this. Settlement always answers this to a customer key | Use a key with the scope |
| 403 | account_unavailable | The account is paused | Contact the operator |
| 403 | live_tools_disabled | Test mode: only tools on this machine can be called | None in test mode |
| 403 | card_paused, card_closed | This card cannot spend. Nothing was held | Ask the owner |
| 403 | key_revoked | This key or its card was stopped. Nothing new starts | Use the new key |
| 403 | tool_not_allowed | This tool is not on the card's list, or the card lists tools and this is a model call | Ask the owner to add it |
| 403 | write_not_allowed | The card is read-only and this tool is not a GET | Use a write card |
| 403 | self_dealing | You tried to buy from your own listing, or one with the same owner | None |
| 403 | self_referral, same_owner_referral, referral_cycle, owner_required | The referral is not allowed, or the owner is not verified | None |
Sign-up and the person's links
From apps/api/src/journey.ts.
| Status | Code | What it means | What to do |
|---|---|---|---|
| 402 | key_required | A request with no key. The body has the start guide | Sign up with POST /v1/agents/start |
| 429 | rate_limited | Too many sign-ups from one address, or from everyone, this hour | Wait, then try once |
| 400 | code_required | A fund or approve link was sent without its 6-digit code. Not counted | Type the code from the agent |
| 400 | code_wrong | The code is wrong. The answer says tries_left. Nothing changed | Check the code with the agent |
| 410 | code_locked | 5 wrong codes: the link is closed | Ask the agent for a new link |
| 410 | link_expired, link_replaced | The link is older than 30 minutes, or the agent made a newer one | Ask the agent for a new link |
| 409 | link_used | The link was already used | Nothing more is needed |
| 404 | link_not_found | No such link | Ask the agent for a new link |
| 403 | csrf_failed, origin_refused | The request did not come from the link's own page | Open the link and press the button there |
| 503 | funding_unavailable | Real payment is not connected in this build | Use the test payment |
404: not found
not_found (no such route), quote_not_found, reservation_not_found, receipt_not_found, tool_not_found, call_not_found, agent_not_found, cloud_not_found, watch_not_found, wallet_not_found, topup_not_found, approval_not_found, plan_not_found, payment_not_found, referral_code_not_found, repo_not_found, commit_not_found, commit_not_indexed, memory_not_found. All are "No"; check the id.
409: conflicts
| Code | What it means | Retry? |
|---|---|---|
quote_expired, quote_already_used | Get a new quote | After a new quote |
idempotency_conflict | The same idempotency key was used with a different payload | No |
reservation_not_held, reservation_unavailable | The hold is already closed, or a running call owns it | No |
price_changed, payto_changed | The tool changed its price or who gets paid. Nothing was paid | No |
duplicate_call | This tool call was already made. POST /v1/calls with the same key reads the earlier answer | No |
call_not_ratable | That call produced no result to rate | No |
listing_conflict | You already listed that endpoint | No |
payout_destination_missing | No verified owner wallet to pay out to | No |
cloud_not_connected | Connect AWS first | No |
balance_limit, owner_conflict, wallet_conflict, topup_conflict | A funding, owner, wallet or top-up conflict | No |
signature_reused | A wallet-signed message can be used once | Sign a new one |
approval_closed | The top-up approval was already decided | No |
plan_active | You already have this plan | No |
already_refunded, refund_blocked_by_hold | A refund was already made, or a hold blocks it | No |
already_referred, referral_too_late | This account already used a code, or it is too late | No |
index_in_progress, manifest_conflict, parent_not_indexed, commit_not_indexed | A repo index conflict | After the index finishes |
413, 5xx
| Status | Code | What it means | Retry? |
|---|---|---|---|
| 413 | request_too_large | Body over the route's limit (64 KiB on most routes) | No |
| 500 | internal_error | A bug | Yes |
| 502 | challenge_invalid, tool_unreachable, signer_failed | The tool's payment challenge was bad, the tool did not answer, or signing failed | Yes |
| 502 | index_failed | Summarising a repo failed | Yes |
| 503 | cloud_unavailable | Your-own-AWS routes are not wired in this process (npm run dev) | No |
| 503 | capacity_exhausted | Supplier capacity for the day is used | Later |
| 503 | provider_risk_limit | Too much is at risk with this tool's provider right now. Nothing was held | Later |
Tests: tests/integration/errors.test.ts, "every billing error code maps to its HTTP status, including the five that fell back to 400"; tests/integration/http.test.ts, "HTTP maps billing failures onto the right status codes".
chain.watch streams end with an Anthropic-shape error event: rate_limit_error for a cap, billing_error for no balance.
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.