Error Handling
The Bitnob Payouts API is designed for reliability, but various error scenarios can occur during the lifecycle of a payout, especially in a dynamic, cross-asset system like On-the-Fly settlements.
Properly handling errors ensures:
Clean user experience,
Faster operational recovery,
Better financial reconciliation,
Reduced support cases.
This section documents the key error types and how you should respond to them.
1. Expired Quotes
What Happens:
A quote expires before the customer funds the payment address.
No asset is received.
No payout is initiated.
API Behavior:
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.
Webhook Event:
| EVENT | MEANING |
|---|---|
payouts.withdrawal.expired | Quote expired. No payment detected. Payout canceled automatically. |
Developer Action:
Inform the customer to restart the process by requesting a new quote. Always check if expiresAt has passed before showing payment options.
2. Underpayment (Partial Funding)
What Happens:
Customer sends less than the amount specified in the quote.
Bitnob detects asset arrival but amount is insufficient.
System Behavior:
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).
Webhook Event:
| EVENT | MEANING |
|---|---|
payouts.asset.received | Asset received. Funding may be partial. |
payouts.withdrawal.processing | Processing payout with adjusted fiat amount. |
payouts.withdrawal.success | Payout delivered (adjusted for underpayment). |
Developer Action:
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."
3. Overpayment (Excess Funding)
What Happens:
Customer sends more than the amount quoted.
System Behavior:
Bitnob processes the original intended fiat payout amount.
Extra funds are credited to the customer's internal balance (or future refund workflow).
Developer Action:
No user action required — payout proceeds. Track excess amounts internally for reporting or refund offers.
4. Payment Sent After Expiry
What Happens:
Payment is received on-chain, but after the quote expiry window.
System Behavior:
Bitnob may auto-refund depending on configuration,
Or credit the amount to customer’s internal balance,
Or require manual support ticket for resolution.
Developer Action:
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.
5. Funding Transaction Stuck or Delayed on Blockchain
What Happens:
Customer’s payment takes too long to confirm due to low mining fee.
System Behavior:
Asset detection (assetReceivedAt) may happen but assetConfirmedAt is delayed.
Payout is not initiated until blockchain confirmation thresholds are satisfied.
Developer Action:
Inform users about minimum recommended Bitcoin/USDT gas fees. Show clear UI for "awaiting confirmations" if payment is detected but not yet usable.
6. Payout Delivery Failure
What Happens:
Funding is successful,
Payout is initiated,
Bank or Mobile Money operator rejects the payout (e.g., invalid account, service downtime).
Webhook Event:
| EVENT | MEANING |
|---|---|
payouts.withdrawal.failed | Payout rejected at delivery phase. |
Developer Action:
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).
7. Compliance or Risk Rejection
What Happens:
After funding, payout is rejected for compliance reasons (e.g., flagged recipient, country restrictions).
Webhook Event:
| EVENT | MEANING |
|---|---|
payouts.withdrawal.rejected | Payout blocked at compliance/risk phase. |
Developer Action:
Capture failureReason from webhook. Notify user or initiate follow-up support process. Ensure compliance settings are up to date with regulatory policies.
