> ## Documentation Index
> Fetch the complete documentation index at: https://v2.docs.conduit.financial/llms.txt
> Use this file to discover all available pages before exploring further.

# RAIL_UNAVAILABLE error

> The payment rail was temporarily unavailable when the transaction was attempted; no funds moved

## 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.

```json theme={null}
{
  "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

<Note>
  This is a retryable terminal state. Submit a new transaction with exponential
  backoff starting at 30 seconds. The original transaction cannot be resumed.
</Note>

**1. Confirm the terminal state**

```bash theme={null}
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:

```bash theme={null}
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

## Related webhooks

The `transaction.failed` event fires when the rail is unreachable:

```json theme={null}
{
  "type": "transaction.failed",
  "data": {
    "transactionId": "txn_abc123",
    "failureCode": "rail_unavailable"
  }
}
```

## Related endpoints

* [GET /v2/transactions/:id](/api-reference/transactions/get-a-transaction-by-id) -- read transaction state
* [POST /v2/payouts](/api-reference/payouts/create-a-payout) -- submit a new payout