Error Handling and Failure Scenarios

Robust error handling is critical when working with stablecoin transfers across multiple blockchains. The withdrawal error responses list the codes you should handle. Failures can occur at various stages—during validation, broadcasting, or on-chain confirmation. Bitnob is designed to surface these issues clearly, let you respond safely, and maintain system integrity.

Categories of Failures

Pre-validation failures are returned synchronously — see Error Responses. Anything after broadcast is reported asynchronously through the withdrawal status lifecycle and its webhooks.

failure stage	common cause	recovery strategy
Pre-validation	Invalid address, unsupported chain/token	Return 400 error with descriptive message
Broadcast error	RPC node issues, network congestion	Retry or requeue transfer
On-chain failure	Out-of-gas, revert from smart contract, frozen token	Emit transfer.failed webhook and unlock balance
Webhook delivery	Timeout, non-2xx response	Retry delivery with exponential backoff

Error Response Example

If a transfer fails validation (e.g., unsupported chain) — validate the destination with Validate Address first to avoid this class of error:

Validation Error Response

Failure Webhook: transfer.failed

When a transfer is initiated successfully but fails during execution (e.g., due to a revert or RPC issue), Bitnob will emit a transfer.failed webhook. Held funds are returned to your available balance when a withdrawal reaches the terminal failed state:

transfer.failed Webhook Payload

Idempotency and Duplicate Submissions

You must use a unique reference per transfer — it is a required field on the withdrawal request. If the same reference is submitted twice:

If the first succeeded: the second call will return the same response

If the first failed: the second call may retry, or return an error, depending on the failure reason

Client logic should not blindly retry on failure without checking webhook results.

Retry Patterns

For network or RPC-related errors, design your system to:

Use exponential backoff for retries

Avoid retry storms during congestion events

Degrade gracefully and notify support teams

For webhook retries:

Bitnob will retry failed deliveries automatically

You can monitor undelivered webhooks from the Dashboard

Retry logs include timestamps, error responses, and attempt count

Recovery Tools for Operations Teams

Dashboard visibility of failed transactions and retry logs

Searchable logs by reference, status, chain or token — the same filters are available programmatically via the transaction query parameters, and a single record can be pulled with Get Transaction By ID Or Reference

Manual retry options (optional toggle in UI)

Export CSV of failed events for compliance/auditing