API reference
Errors
Error codes the sandbox returns.
Every error is JSON with a stable error code and, usually, a human-readable message. Branch on error, show message.
json
{ "error": "insufficient_funds", "message": "insufficient_funds" }HTTP status follows the kind of error: 400 bad input, 401 not signed in or bad key, 403 not allowed (including agent policy blocks), 404 not found, 409 wrong state, 429 limit reached. x402 resources answer 402 with the requirement body instead. Codes:
| Code | Where |
|---|---|
insufficient_funds | Transfers, agent payments |
unknown_recipient | Transfers |
self_transfer | Transfers |
paused | Agent payments |
over_per_request | Agent payments |
over_daily_cap | Agent payments |
host_not_allowed | Agent x402 payments |
a2a_not_allowed | Agent-to-agent |
insufficient_funds | Not enough balance |
invalid_amount | Amount is not a positive number with up to 6 decimals |
unauthorized | No session and no key |
invalid_key | Key unknown or revoked |
agent_key_not_allowed | Agent key used on an account endpoint |
agent_key_required | Account credentials used on /v1/agent/* |
faucet_limit | Faucet over 1,000 SUSD today (429) |
handle_taken | PATCH /v1/me (409) |
invoice_not_open | Paying or voiding a paid or void invoice (409) |
self_payment | Paying your own invoice |
invalid_policy | Per-request max above the daily cap |
unsupported_requirement | x402 requirement not for railpay-sandbox / SUSD |
payment_required | x402 resources (HTTP 402) |
| invalid_payment / payment_expired / payment_mismatch / payment_already_used | x402 retry rejected (HTTP 402) |