Error Handling and Failure Scenarios

Robust error handling is critical when working with stablecoin transfers across multiple blockchains. 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

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):

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:

transfer.failed Webhook Payload

Idempotency and Duplicate Submissions

You must use a unique reference per transfer. 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

Manual retry options (optional toggle in UI)

Export CSV of failed events for compliance/auditing