| Situation | What to do |
|---|---|
| Timeout or connection error on Create Payout, Create Transfer, Create Virtual Account, Upload Document, Submit Agreement Actions | Retry with the same Idempotency-Key and byte-identical body until you get a response |
| Timeout on Create Beneficiary, Create Payout Destination, Create Webhook Endpoint | Do not retry blind. List the resource and match on your own fields (name and details, URL) before creating again |
| Timeout on Create Wallet | List Wallets; if the pair exists, use it |
| Timeout on Create FX Quote | Request a new quote |
| Timeout on Execute FX Quote | Get FX Quote: executed_at set means it executed; find the trade in List FX Trades by quote_id. A retry returns 422 FX_QUOTE_INVALID either way |
200 with status: failed from Execute FX Quote | Treat as not converted; funds were released; re-quote |
401 Nonce already used on a retry | Rebuild all four headers with a fresh nonce and timestamp |
429 | Sleep until the next clock minute, then retry |
502 GATEWAY_ERROR on Create Virtual Account Group or Upload Document | Repeat the same request (same key for uploads) |
502 on Create Wallet | Retry |
503 | Retry with backoff |
500 SERVICE_ERROR on Create Payout | Read List Payouts for the last minute and match on your key’s body; retry serially if absent |
| Webhook receiver down for more than 45 hours | Reconcile with List Payins, List Payouts, List Transfers over the outage window, keyed on created |
Group onboarding_status rejected or closed | Stop polling; contact support |
| Beneficiary or destination disabled by mistake | Contact support, or create a new one |
End-to-end flows