Skip to main content

​
What happened

The payment rail rejected the transaction based on its own rules — for example, an amount limit, a frequency cap, or a restriction on the recipient. No funds were moved. The transaction is in a terminal failed state with failureCode: RAIL_POLICY_REJECTED. 
{
  "type": "RAIL_POLICY_REJECTED",
  "title": "Payment rail rejected the transaction",
  "status": 422,
  "detail": "The payment rail's policy rejected the transaction.",
  "resolution": "Adjust the amount, recipient, or wait period and submit a new transaction.",
  "docs": "/errors#rail-policy-rejected",
  "instance": "/v2/transactions/txn_abc123",
  "correlationId": "corr_xyz789",
  "timestamp": "2026-01-15T09:30:00.000Z"
}

​
Common causes

  • Amount limit — the transaction amount exceeds the per-transaction or daily limit on the rail
  • Frequency cap — the recipient or sender has exceeded the number of transfers allowed in a given period
  • Recipient restriction — the recipient’s institution does not accept transfers from this corridor or rail
  • Invalid account details — the routing number, IBAN, or account number does not pass the rail’s validation rules

​
Recovery

This is a terminal state. No funds were moved. Investigate the rejection reason before resubmitting.
1. Confirm the terminal state 
curl -X GET https://api.conduit.financial/v2/transactions/txn_abc123 \
  -H "x-api-key: YOUR_API_KEY"
2. Review the recipient details Verify that the routing number, account number, and recipient name are correct. For SEPA transfers, confirm the IBAN format and BIC. 3. Check the amount Confirm the transaction amount falls within the rail’s per-transaction limits. If the amount is near a known limit, split the transfer or ask the customer to try a smaller amount. 4. Submit a new transaction after resolving the issue 
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": "1234567890",
        "routingNumber": "021000021",
        "accountType": "CHECKING"
      }
    }
  }'

​
Prevention

  • Validate recipient details at collection time — use the requirements endpoint to confirm required fields and formats before accepting recipient information
  • Respect per-transfer limits — check your account’s configured rail limits and enforce them in your UI before submitting
  • Handle transaction.failed with this code — branch on failureCode === 'RAIL_POLICY_REJECTED' to surface a “the recipient’s bank rejected this transfer” message with a retry option after the user corrects details
The transaction.failed event fires when the rail rejects the transaction: 
{
  "type": "transaction.failed",
  "data": {
    "transactionId": "txn_abc123",
    "failureCode": "RAIL_POLICY_REJECTED"
  }
}