401 authentication_required
Missing or invalid Bearer key.
Use the correct test or live secret key in the Authorization header.
Debug faster
Turn every API error into a next action.
Most integration issues fall into authentication, validation, webhook, route support, or polling behavior. This guide maps the symptom to the next fix.
400 validation_error
Required field is missing or invalid.
Check amount, currency, network, webhook URL, wallet address, and JSON format.404 not_found
Payment session or endpoint was not found.
Confirm the session ID and route path. For public status use /payments/{id}/status.409 fee_delegation_unavailable
Fee delegation settings, route, or network support are not active.
Use standard wallet checkout or activate the merchant policy and supported route first.422 webhook delivery failed
The merchant endpoint did not return a 2xx status.
Check HTTPS, raw body parsing, signature verification, timeout, and firewall rules.429 rate_limited
Too many authenticated API requests.
Back off, retry later, and avoid polling too aggressively.Still blocked?
Send the request ID, endpoint, session ID, response code, and sanitized payload. Never send private keys or webhook secrets.
Contact support Open API docs Inspect JSON-RPC Errors in MCP Playground Debug 422 Webhook Signatures
Official NPM SDKs (v0.2.0) & Remote MCP Server
Integrate Faster with Official XPayr Packages & Zero-Install MCP
Install @xpayr/node-sdk (v0.2.0), @xpayr/payment-evidence (v0.2.0), @xpayr/extension-kit (v0.2.0), or @xpayr/mcp-server (v1.0.0) from NPM, or execute live JSON-RPC 2.0 tool calls via POST https://xpayr.com/api/mcp.