Skip to main content

What happened

The payment rail was not available when the transaction was attempted. No funds were moved. The transaction is in a terminal failed state with failureCode: rail_unavailable. This is a transient infrastructure failure, not a problem with your request or the recipient’s details. The same request is likely to succeed once the rail recovers.

Common causes

  • Scheduled maintenance — the rail or its underlying network is in a maintenance window
  • Transient outage — the rail experienced an unexpected interruption
  • All routing options exhausted — every configured provider for this corridor was unavailable simultaneously

Recovery

This is a retryable terminal state. Submit a new transaction with exponential backoff starting at 30 seconds. The original transaction cannot be resumed.
1. Confirm the terminal state
2. Wait and resubmit Start with a 30-second delay and double on each attempt. Most rail outages resolve within minutes:
Use a fresh Idempotency-Key for each new attempt. 3. Contact support if the outage persists If the rail is consistently unavailable after multiple retries over 30+ minutes, contact support with:
  • The instance value from the error response
  • The rail and corridor you are requesting
  • The correlation IDs from the failed attempts

Prevention

  • Implement retry logic with backoff — wrap payout requests in a retry loop with exponential backoff (30s, 60s, 120s) and a cap of 3-5 attempts
  • Handle transaction.failed with this code — branch on failureCode === 'rail_unavailable' to surface a “temporarily unavailable, please try again shortly” message rather than a permanent failure state
  • Consider alternative rails — if your integration supports multiple rails for a corridor, route around the unavailable one on retry
The transaction.failed event fires when the rail is unreachable: