Error Handling

Clean user experience,

Faster operational recovery,

Better financial reconciliation,

Reduced support cases.

A quote expires before the customer funds the payment address.

No asset is received.

No payout is initiated.

If customer tries to use an expired quoteId, API will return a 400 Bad Request with reason quote_expired.

Trip is not fully created or remains in an "expired" incomplete state.

Inform the customer to restart the process by requesting a new quote.

Always check if expiresAt has passed before showing payment options.

Customer sends less than the amount specified in the quote.

Bitnob detects asset arrival but amount is insufficient.

Payout still processes.

The fiat amount delivered is pro-rated based on amount actually received.

Difference is automatically calculated at the original quoted FX rate (within allowed margin).

Always listen for the actual amountReceived field in webhook payloads.

Show users the final delivered amount post-processing if underpayment happens.

Optionally notify the user that "partial payment received, adjusted payout delivered."

Customer sends more than the amount quoted.

Bitnob processes the original intended fiat payout amount.

Extra funds are credited to the customer's internal balance (or future refund workflow).

No user action required — payout proceeds.

Track excess amounts internally for reporting or refund offers.

Payment is received on-chain, but after the quote expiry window.

Bitnob may auto-refund depending on configuration,

Or credit the amount to customer’s internal balance,

Or require manual support ticket for resolution.

Always encourage users to pay immediately.

Handle webhook events like payouts.withdrawal.expired carefully — double-check if an asset eventually arrives after expiry and reconcile manually if needed.

Customer’s payment takes too long to confirm due to low mining fee.

Asset detection (assetReceivedAt) may happen but assetConfirmedAt is delayed.

Payout is not initiated until blockchain confirmation thresholds are satisfied.

Inform users about minimum recommended Bitcoin/USDT gas fees.

Show clear UI for "awaiting confirmations" if payment is detected but not yet usable.

Funding is successful,

Payout is initiated,

Bank or Mobile Money operator rejects the payout (e.g., invalid account, service downtime).

Listen for payouts.withdrawal.failed.

Retrieve failureReason from webhook or API fetch call.

Display clear messages to users (e.g., "Payment rejected due to invalid account number.").

Work with Bitnob support or retry payout after correcting beneficiary details (where allowed).

Your webhook server is down or responds with non-200 status codes.

Immediate retry on first failure,

Exponential backoff (e.g., retry after 1 min, 5 min, 15 min),

Retried up to a maximum threshold (e.g., 24 hours).

Always build idempotent webhook handlers.

Log all received webhook payloads.

Ensure fast 200 OK responses even if you need to process asynchronously.

Consider implementing manual reconciliation fallback via GET /payouts/fetch/:reference and GET /payouts/trips/:tripId.

After funding, payout is rejected for compliance reasons (e.g., flagged recipient, country restrictions).

Capture failureReason from webhook.

Alert your internal compliance or ops teams for review.

Engage Bitnob account managers where necessary to resolve.

Always track by tripId to see full status timeline.

Listen for both funding events (asset.received) and payout events (withdrawal.processing, withdrawal.success, withdrawal.failed).

Build alerting for payout delays beyond expected SLA windows.

Educate users on fast payment behavior (to prevent expiry or stuck payments).

Pre-validate beneficiary bank accounts or wallets where possible.

Payments can be late, partial, or excess.

Blockchain can delay confirmations.

Banks and Mobile Money systems can intermittently fail.

Compliance systems may block payouts.