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. 
{
  "type": "RAIL_UNAVAILABLE",
  "title": "Payment rail unavailable",
  "status": 503,
  "detail": "No viable payment rail was available for the requested corridor. No funds were moved.",
  "resolution": "Retry later. If the corridor is persistently unavailable, contact support.",
  "docs": "/errors#rail-unavailable",
  "instance": "/v2/transactions/txn_abc123",
  "correlationId": "corr_xyz789",
  "timestamp": "2026-01-15T09:30:00.000Z"
}

​
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 
curl -X GET https://api.conduit.financial/v2/transactions/txn_abc123 \
  -H "x-api-key: YOUR_API_KEY"
2. Wait and resubmit Start with a 30-second delay and double on each attempt. Most rail outages resolve within minutes: 
curl -X POST https://api.conduit.financial/v2/payouts \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Idempotency-Key: idem_NEW_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cus_abc123",
    "virtualAccountId": "vac_abc123",
    "assetAmount": {"code": "USD", "amount": "500.00"},
    "destination": {
      "recipient": {
        "rail": "us",
        "type": "INDIVIDUAL",
        "firstName": "Jane",
        "lastName": "Doe",
        "accountNumber": "...",
        "routingNumber": "...",
        "accountType": "CHECKING"
      }
    }
  }'
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: 
{
  "type": "transaction.failed",
  "data": {
    "transactionId": "txn_abc123",
    "failureCode": "RAIL_UNAVAILABLE"
  }
}