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