Errors

Fixture onlyChecked 16 November 2026

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.

RoutesShape
/v1/messages, /v1/messages/count_tokensAnthropic: { "type": "error", "error": { "type", "message" } }
/v1/chat/completions, /v1/responsesOpenAI: { "error": { "message", "type", "param": null, "code" } }
Every other /v1/* routePetrova: { "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

Statuserror.typeWhenRetry?Test
400invalid_request_errorBad JSON, no model, bad max_tokens, a model not in the price table, a malformed agent or session idNotests/unit/messages.test.ts
401authentication_errorNo key, or a bad or revoked keyNo"auth accepts x-api-key or a bearer token and rejects anything else"
402billing_errorNot enough balance (x-should-retry: false)No: add fundserrors.test.ts, "no balance on /v1/messages is a Claude-shape billing_error, not retried; on OpenAI routes it is insufficient_quota"
403permission_errorThe key lacks quote:write (or memory:read when you send x-petrova-repo)Notests/integration/memory.test.ts
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: false)Noerrors.test.ts, "a body that is too large comes back in each route's own shape"
429rate_limit_errorA 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"
429rate_limit_errorLoop pause: the same tool call 5 times in the last 20 (x-petrova-loop: pause, x-should-retry: false). Nothing was heldNo: fix the loop"a repeating tool loop is paused before it is paid for again"
502api_errorNo supplier could be reached. The hold was released; you paid nothingYes"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: false). You paid nothingLatertests/integration/capacity.test.ts
429 / 500 / 529as the supplier sent itA supplier failed before the first word and so did every other oneYes"a 529 from the first upstream fails over to the next, stream and non-stream"

Model calls: OpenAI shape

StatuscodeWhenRetry?
400invalid_requestBad request; n other than 1; previous_response_id (not supported)No
401invalid_api_keyNo key or a bad keyNo
403permission_deniedMissing scope, or account not availableNo
409request_id_reusedThe same request id was already usedNo
413request_too_largeBody over 32 MiBNo
429insufficient_quotaNot enough balance (x-should-retry: false). Codex stops on this codeNo
429spend_limit_reached (type insufficient_quota)A spend cap would be crossedNo
429loop_pausedLoop pauseNo
503server_is_overloadedEvery 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

CodeWhat it means
invalid_requestA field is missing or malformed. Also used for any code not in the status map
invalid_quote, payload_mismatchThe quote does not match the payload you sent with it
invalid_settlementA settlement body is wrong (operator only)
invalid_budgetA cap amount or reference is wrong, or the project or key is not in your account
invalid_inputs, tool_not_callableThe 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_withdrawalA listing, earning rule or withdrawal amount is wrong (withdrawals must be whole micro-USD)
invalid_role, external_id_mismatchThe AWS role ARN or external id is wrong
invalid_filterA chain.watch filter is wrong
invalid_funding, invalid_owner, invalid_wallet, invalid_topup, invalid_planFunding, owner, wallet, top-up or plan input is wrong
blob_mismatch, blob_too_large, missing_blobsA repo index upload is wrong or too big (256 KiB per file)

401, 402, 403

StatusCodeWhat it meansWhat to do
401unauthorizedNo valid key. Most routes take only Authorization: Bearer ptrv_test_...Check the key and the header
401invalid_signatureA wallet-signed message did not verifySign again
402insufficient_balanceNot enough balance for the holdAdd funds
402budget_exceededA cap would be crossedRaise the cap or wait
402over_max_costThe tool costs more than your max_cost_nusdRaise your max
402per_call_limitThis call is above the card's per-call limit. It never waitsAsk for less, or have the owner raise the limit
402approval_requiredAbove the card's approval line, on a route that cannot wait, such as a seller listingHave the owner raise the line
402insufficient_withdrawableYou asked to withdraw more than is withdrawableAsk for less
402not_fundedAn agent wallet asked for a key before any top-up was creditedTop up first
403scope_deniedThe key cannot do this. Settlement always answers this to a customer keyUse a key with the scope
403account_unavailableThe account is pausedContact the operator
403live_tools_disabledTest mode: only tools on this machine can be calledNone in test mode
403card_paused, card_closedThis card cannot spend. Nothing was heldAsk the owner
403key_revokedThis key or its card was stopped. Nothing new startsUse the new key
403tool_not_allowedThis tool is not on the card's list, or the card lists tools and this is a model callAsk the owner to add it
403write_not_allowedThe card is read-only and this tool is not a GETUse a write card
403self_dealingYou tried to buy from your own listing, or one with the same ownerNone
403self_referral, same_owner_referral, referral_cycle, owner_requiredThe referral is not allowed, or the owner is not verifiedNone

From apps/api/src/journey.ts.

StatusCodeWhat it meansWhat to do
402key_requiredA request with no key. The body has the start guideSign up with POST /v1/agents/start
429rate_limitedToo many sign-ups from one address, or from everyone, this hourWait, then try once
400code_requiredA fund or approve link was sent without its 6-digit code. Not countedType the code from the agent
400code_wrongThe code is wrong. The answer says tries_left. Nothing changedCheck the code with the agent
410code_locked5 wrong codes: the link is closedAsk the agent for a new link
410link_expired, link_replacedThe link is older than 30 minutes, or the agent made a newer oneAsk the agent for a new link
409link_usedThe link was already usedNothing more is needed
404link_not_foundNo such linkAsk the agent for a new link
403csrf_failed, origin_refusedThe request did not come from the link's own pageOpen the link and press the button there
503funding_unavailableReal payment is not connected in this buildUse 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

CodeWhat it meansRetry?
quote_expired, quote_already_usedGet a new quoteAfter a new quote
idempotency_conflictThe same idempotency key was used with a different payloadNo
reservation_not_held, reservation_unavailableThe hold is already closed, or a running call owns itNo
price_changed, payto_changedThe tool changed its price or who gets paid. Nothing was paidNo
duplicate_callThis tool call was already made. POST /v1/calls with the same key reads the earlier answerNo
call_not_ratableThat call produced no result to rateNo
listing_conflictYou already listed that endpointNo
payout_destination_missingNo verified owner wallet to pay out toNo
cloud_not_connectedConnect AWS firstNo
balance_limit, owner_conflict, wallet_conflict, topup_conflictA funding, owner, wallet or top-up conflictNo
signature_reusedA wallet-signed message can be used onceSign a new one
approval_closedThe top-up approval was already decidedNo
plan_activeYou already have this planNo
already_refunded, refund_blocked_by_holdA refund was already made, or a hold blocks itNo
already_referred, referral_too_lateThis account already used a code, or it is too lateNo
index_in_progress, manifest_conflict, parent_not_indexed, commit_not_indexedA repo index conflictAfter the index finishes

413, 5xx

StatusCodeWhat it meansRetry?
413request_too_largeBody over the route's limit (64 KiB on most routes)No
500internal_errorA bugYes
502challenge_invalid, tool_unreachable, signer_failedThe tool's payment challenge was bad, the tool did not answer, or signing failedYes
502index_failedSummarising a repo failedYes
503cloud_unavailableYour-own-AWS routes are not wired in this process (npm run dev)No
503capacity_exhaustedSupplier capacity for the day is usedLater
503provider_risk_limitToo much is at risk with this tool's provider right now. Nothing was heldLater

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.