Error registry
Every rejection walras emits, on every path, carries a machine-readable code from one of the disjoint taxonomies below plus a non-null human-readable reason (RFP 3.6). Branch on the code; the text is an explanation, never a contract.
Taxonomy discipline (DECISIONS D-007, D-028): codes originated by
@x402/stellar's payment scheme are passed through verbatim — walras never
invents a parallel name for a rejection the scheme already codes. walras_*
codes exist only for surfaces the scheme is silent about. A test greps the
installed @x402/stellar bundle for the inherited set, so upstream drift breaks
the build rather than silently degrading a rejection reason (FACTS F-063).
Where codes appear
| Taxonomy | Appears in |
|---|---|
| Scheme verify codes | VerifyResponse.invalidReason (also settle, via mandatory re-verification) |
| Scheme settle codes | SettleResponse.errorReason |
| walras envelope codes | invalidReason / errorReason on 4xx/5xx; error.code on discovery endpoints |
| Bazaar soft-drop codes | the code field inside the EXTENSION-RESPONSES header's bazaar object |
| MCP tool codes | structuredContent.errorCode of an isError tool result |
Inherited scheme codes — verify path (30)
Emitted by ExactStellarScheme in @x402/stellar (FACTS F-045). The text
paraphrases the corresponding MUST in specs/schemes/exact/scheme_exact_stellar.md
at the pinned SHA. Note the reachability ordering of FACTS F-064: auth-entry and
transfer-event codes fire only after simulation succeeds, so on a network where
simulation cannot succeed, payloads collapse to
invalid_exact_stellar_payload_simulation_failed.
| Code | Meaning |
|---|---|
invalid_x402_version |
The payment payload declares an x402 version this scheme does not support. |
unsupported_scheme |
The scheme in the payment payload or the requirements is not 'exact'. |
network_mismatch |
paymentPayload.accepted.network does not match paymentRequirements.network. |
invalid_network |
The requested network is not a known Stellar network. |
invalid_exact_stellar_payload_malformed |
payload.transaction is missing or is not decodable as Stellar transaction XDR. |
invalid_exact_stellar_payload_wrong_operation |
The transaction must carry exactly one invokeHostFunction operation invoking a contract. |
invalid_exact_stellar_payload_unsafe_tx_or_op_source |
The transaction or operation source is a facilitator signing address, which is not permitted. |
invalid_exact_stellar_payload_wrong_asset |
The invoked contract address does not match paymentRequirements.asset. |
invalid_exact_stellar_payload_wrong_function_name |
The invoked function is not transfer(from, to, amount) with exactly three arguments. |
invalid_exact_stellar_payload_facilitator_is_payer |
The transfer 'from' address is a facilitator signing address, which is not permitted. |
invalid_exact_stellar_payload_wrong_recipient |
The transfer 'to' address does not equal paymentRequirements.payTo. |
invalid_exact_stellar_payload_wrong_amount |
The transfer amount does not equal paymentRequirements.amount exactly. |
invalid_exact_stellar_payload_simulation_failed |
Re-simulation of the transaction against current ledger state did not succeed. |
invalid_exact_stellar_payload_fee_exceeds_maximum |
The simulation-derived settlement fee exceeds the configured maxTransactionFeeStroops ceiling. |
invalid_exact_stellar_payload_event_not_transfer |
A contract event emitted by the simulation is not a SEP-41 transfer event. |
invalid_exact_stellar_payload_event_missing_contract_id |
A simulation transfer event carries no contract id. |
invalid_exact_stellar_payload_event_wrong_asset |
A simulation transfer event was emitted by a contract other than the required asset. |
invalid_exact_stellar_payload_no_transfer_events |
The simulation emitted no transfer event, so no balance change could be confirmed. |
invalid_exact_stellar_payload_multiple_transfers |
The simulation emitted more than one transfer event; only the single expected transfer is allowed. |
invalid_exact_stellar_payload_event_wrong_from |
The simulated transfer debits an address other than the payer named in the transaction. |
invalid_exact_stellar_payload_event_wrong_to |
The simulated transfer credits an address other than paymentRequirements.payTo. |
invalid_exact_stellar_payload_event_wrong_amount |
The simulated transfer moves an amount other than paymentRequirements.amount. |
invalid_exact_stellar_payload_no_auth_entries |
The invokeHostFunction operation carries no authorization entries. |
invalid_exact_stellar_payload_unsupported_credential_type |
An authorization entry uses credentials other than sorobanCredentialsAddress. |
invalid_exact_stellar_payload_facilitator_in_auth |
A facilitator address appears in an authorization entry, which is not permitted. |
invalid_exact_stellar_signature_expiration_too_far |
An authorization entry expires beyond currentLedger + ceil(maxTimeoutSeconds / estimatedLedgerSeconds). |
invalid_exact_stellar_payload_has_subinvocations |
An authorization entry authorizes sub-invocations beyond the transfer itself. |
invalid_exact_stellar_payload_missing_payer_signature |
The payer's authorization entry is unsigned. |
invalid_exact_stellar_payload_unexpected_pending_signatures |
One or more authorization entries still await a signature. |
unexpected_verify_error |
Verification failed with an unexpected error inside the payment scheme. |
Inherited scheme codes — settle path (7)
| Code | Meaning |
|---|---|
verification_failed |
Settle re-ran verification independently, as the spec requires, and verification did not pass. |
settle_exact_stellar_signer_selection_failed |
No facilitator signing account could be selected to source the settlement transaction. |
settle_exact_stellar_transaction_signing_failed |
The facilitator could not sign the rebuilt settlement transaction. |
settle_exact_stellar_fee_bump_signing_failed |
The facilitator could not sign the fee-bump wrapper for the settlement transaction. |
settle_exact_stellar_transaction_submission_failed |
The settlement transaction was rejected when submitted to the Stellar network. |
settle_exact_stellar_transaction_failed |
The settlement transaction was submitted but did not reach SUCCESS on-chain. |
unexpected_settle_error |
Settlement failed with an unexpected error inside the payment scheme. |
walras envelope codes (10)
Originated by the HTTP wrapper for what the scheme is silent about: envelope validation, kind routing, discovery query interpretation, and wrapper faults.
| Code | Meaning |
|---|---|
walras_malformed_request_body |
The request body was absent, was not valid JSON, or was not a JSON object. |
walras_missing_payment_payload |
The request body has no 'paymentPayload' object. See x402 v2 spec section 7.1. |
walras_missing_payment_requirements |
The request body has no 'paymentRequirements' object. See x402 v2 spec section 7.1. |
walras_unsupported_x402_version |
paymentPayload.x402Version names a protocol version this facilitator does not serve. |
walras_unsupported_kind |
The (scheme, network) pair is not advertised by this facilitator. See GET /supported. |
walras_unknown_route |
No route is mounted at this method and path. This facilitator serves POST /verify, POST /settle, GET /supported, GET /discovery/resources, GET /discovery/search, and GET /health. |
walras_invalid_query_parameter |
A query parameter could not be interpreted. limit and offset must be non-negative integers; filter parameters must not repeat. |
walras_missing_search_query |
GET /discovery/search requires a non-empty 'query' parameter. See specs/extensions/bazaar.md — the parameter is named 'query', not 'q'. |
walras_invalid_search_cursor |
The 'cursor' parameter is not a cursor this facilitator issued for this query and filter combination. Repeat the search without a cursor to start a new walk. |
walras_internal_error |
The facilitator failed to process the request. This says nothing about the payment's validity. |
Bazaar cataloging soft-drop codes (7)
Never appear in a payment response — only inside the bazaar object of the
EXTENSION-RESPONSES header, alongside the human-readable rejectedReason
the spec expects (FACTS F-024; DECISIONS D-014). Every code names a defect in
the client's payload; internal indexer faults omit the header entirely rather
than blaming the client (DECISIONS D-025).
| Code | Meaning |
|---|---|
bazaar_extension_not_object |
The bazaar extension must be a JSON object with 'info' and 'schema' fields. |
bazaar_extensions_too_large |
The extensions object exceeds the 64 KiB indexing limit and was not cataloged. |
bazaar_spec_validation_failed |
The discovery info violates the bazaar protocol invariants. |
bazaar_schema_validation_failed |
The discovery info failed schema validation. |
bazaar_schema_too_complex |
The discovery schema is too large or deeply nested to validate within the indexer's bounds. |
bazaar_resource_url_invalid |
resource.url must be an absolute http(s) URL without credentials. |
bazaar_listing_owned_by_other_payee |
This resource is already cataloged for a different payment recipient; a listing can only be updated by payments to its original payTo. |
MCP tool codes (11)
Originated by packages/mcp-server for the surface only it owns (DECISIONS
D-028). Facilitator and scheme codes cross the MCP boundary verbatim; these
cover argument validation, id resolution, reachability, spend policy, and
payment outcomes the upstream leaves uncoded.
| Code | Meaning |
|---|---|
walras_mcp_wallet_not_configured |
paid_call requires a wallet. Set CLIENT_STELLAR_PRIVATE_KEY (an S... ed25519 seed) in the environment of this MCP server. search_resources works without one. |
walras_mcp_invalid_arguments |
The tool arguments are inconsistent. Provide either resourceId (from search_resources) or url — plus toolName when the target is an MCP tool. |
walras_mcp_unknown_resource_id |
resourceId does not decode to a listing this catalog has. Re-run search_resources and use an id from its results. |
walras_mcp_facilitator_unreachable |
The walras facilitator did not answer at the transport level. Check FACILITATOR_URL and that the facilitator is running. |
walras_mcp_search_failed |
The facilitator rejected the discovery request without a machine-readable code this server recognizes. |
walras_mcp_resource_unreachable |
The target resource did not answer at the transport level. |
walras_mcp_resource_error |
The target resource answered with an error that is not a payment challenge. No payment was made. |
walras_mcp_payment_declined_by_policy |
The payment demanded exceeds this server's spend cap. Nothing was paid. Raise WALRAS_MCP_MAX_AMOUNT (USDC base units, 7 decimals) to allow it. |
walras_mcp_payment_not_settled |
A payment was attempted but no successful settlement receipt came back. |
walras_mcp_tool_call_failed |
The MCP tool call to the target server failed. |
walras_mcp_internal_error |
This MCP server failed to process the request. This says nothing about the payment's validity. |
References
FACTS rows and DECISIONS entries cited above resolve in
../FACTS.md and ../DECISIONS.md.