Errors and Retries

Use this page to decide when to retry, when to stop and fix the request, and how to avoid duplicate financial operations when the result of an API call is uncertain.

✅ Before you implement retries

Set these controls up before you move money in production:

1. Send an Idempotency-Key on any write request that can create a financial side effect.
2. Generate a Vfx-Correlation-Id for each logical operation so you can trace retries across systems.
3. Store request IDs, payment IDs, and webhook events so you can reconcile uncertain outcomes.
4. Process webhook updates because the final transaction state may arrive after the original API call.

📇 The Header Registry

Headers provide the metadata for tracing every request through our global stack.

---

🚦 HTTP Status Strategy

Verto utilizes standard HTTP codes to categorize the "severity" of an error.

Retry decision guide

Use this quick rule set when a request fails or times out:

---

📖 Error Code Dictionary

Beyond the HTTP status, the response body contains a specific errorCode string for programmatic handling.

🏦 Wallet & Ledger Errors

💸 Payout & Route Errors

---

🔄 The Retry & Idempotency Loop

🛡️

The Golden Rule: Never Retry Without a Key

If you experience a 503 Service Unavailable or a network timeout while sending a payment, do not just send a new request. You might double-pay!

• Always include an Idempotency-Key header with a unique value (e.g. your own internal DB primary key).
• Verto caches the result for 24 hours. Retrying with the same key will return the original success/failure instead of a new charge.

🛑

Do not retry an open RFI

A Request for Information (RFI) is not a transient API failure. If a payout, beneficiary, FX trade, or onboarding workflow is under review, pause automation and follow Handle RFIs and Compliance Exceptions before creating another request.

Common failure scenarios

---

🎯 Next Steps