Errors

API errors use standard HTTP status codes. Application-level failures also carry a stable errorCode string so you can branch on the cause programmatically instead of parsing messages.

Response format

A failed request returns the matching HTTP status (including 400, 401, 404, 503) with this body:

{
  "message": "Session expired",
  "errorCode": "SESSION_EXPIRED",
  "error": "Bad Request"
}

Session

Deposit addresses

Do not show a previously cached address or QR code after this error. The widget provides a retry action. Missing provider configuration, rejected credentials, malformed provider responses and temporary provider failures all use this safe public error; provider response bodies and credentials are not exposed.

Admin deposit recovery

These codes belong to authenticated dashboard-admin actions, not operator-key endpoints. Refund request bodies and operator callback payloads are unchanged.

PENDING means in-flight or unknown, not confirmed failure or proof of payout. Admin deposit detail additionally exposes sweepIntentStatus and sweepIntentId; SWEPT preserves the original aggregate ownership, gross/net/fee and receipt for finalize-only retries. Recovery is operations-gated; this release provides no automatic reconciliation/reset endpoint.

Withdrawals

A withdrawal is approved by your approval webhook (WITHDRAW_REQUEST). To decline one, return an error with a numeric code — it maps to the errorCode the widget surfaces to the user, all as HTTP 400:

The API also returns one withdrawal error on its own, as HTTP 400:

Headless withdrawals

Errors specific to the headless (widgetless) flow. Supported assets are active Bankroll-registered EVM ERC-20 and Tron TRC20 tokens. Native assets (including TRX), malformed addresses and unsupported chains/tokens are rejected at intent creation or execute.

The execute call fails closed rather than guessing when it cannot price or read availability — it returns HTTP 503 and reserves/queues nothing. Retry a 503 only once price/capacity is available again. Create and execute are idempotent only for the same immutable intent: reuse the same operatorReference and payload for create, and the same sessionRef for execute. Treat 409 as a state/configuration signal rather than blindly retrying it; inspect status or correct the underlying input first. HEADLESS_RETRY_* is the dashboard-admin recovery plane, not an operator-key endpoint.

For Tron, a send timeout, expired native transaction, missing receipt or RPC failure after broadcast uncertainty begins does not prove failure. The request remains RECONCILING, its reservation remains held, and cancel/re-sign/re-send is not allowed. Do not create a new operator reference to work around this state. A definite solid receipt and the configured confirmation depth resolve success or revert.

Transaction limits

Authentication