Error Reasons
Status: draft
Kaspa x402 transports expose upstream x402 error reasons on public PaymentRequired.error, corrective response bodies, facilitator invalidReason, and settlement errorReason fields. Kaspa-specific failures are retained as local diagnostic codes, but they must be mapped before they cross the x402 wire surface.
Public Wire Reasons
| Reason | Used when |
|---|---|
invalid_x402_version | The envelope uses an unsupported x402 version. |
invalid_scheme | The selected scheme is unsupported or malformed. |
invalid_network | The selected Kaspa network is unsupported or inconsistent. |
invalid_payment_requirements | The accepted requirements are not satisfiable or do not match the server offer. |
invalid_payload | The payment payload, extension envelope, signature material, or identifier payload is malformed. |
invalid_transaction_state | The payment is structurally valid but cannot settle because of replay, stale state, conflict, or on-chain mismatch. |
unsupported_scheme | The facilitator or server does not support the requested scheme/action. |
unexpected_settle_error | The server cannot classify a settlement failure more precisely. |
Local Diagnostics
Implementations may log, test, or expose internal diagnostics out of band with Kaspa-specific codes such as:
invalid_kaspa_x402_amount
invalid_kaspa_x402_binding
invalid_kaspa_x402_payload
invalid_kaspa_payment_identifier
missing_kaspa_payment_identifier
kaspa_payment_identifier_conflict
invalid_kaspa_exact_replay
invalid_kaspa_settlement_responseThese local codes are not the public x402 compatibility contract. A server that includes one in logs should still emit the mapped public reason on the x402 wire response.
Source: /spec/errors.md