RailPayDocs
Sandbox. No real funds move and nothing settles on a chain yet. What this means

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:

CodeWhere
insufficient_fundsTransfers, agent payments
unknown_recipientTransfers
self_transferTransfers
pausedAgent payments
over_per_requestAgent payments
over_daily_capAgent payments
host_not_allowedAgent x402 payments
a2a_not_allowedAgent-to-agent
insufficient_fundsNot enough balance
invalid_amountAmount is not a positive number with up to 6 decimals
unauthorizedNo session and no key
invalid_keyKey unknown or revoked
agent_key_not_allowedAgent key used on an account endpoint
agent_key_requiredAccount credentials used on /v1/agent/*
faucet_limitFaucet over 1,000 SUSD today (429)
handle_takenPATCH /v1/me (409)
invoice_not_openPaying or voiding a paid or void invoice (409)
self_paymentPaying your own invoice
invalid_policyPer-request max above the daily cap
unsupported_requirementx402 requirement not for railpay-sandbox / SUSD
payment_requiredx402 resources (HTTP 402)
invalid_payment / payment_expired / payment_mismatch / payment_already_usedx402 retry rejected (HTTP 402)

The RailPay app runs in Sandbox mode. Balances are in Sandbox USD (SUSD). No real funds move and nothing settles on a chain. Chains, stablecoins, card issuing, ramps, fees and yield are TBD.

© 2026 RailPay. Built as practical payment infrastructure, not a token or fundraising project.