Returns and failed payouts

Updated 19 September 20263 min read

On this page

Not every payout arrives. A bank can reject a payment before it is delivered, which Ledgerline reports as failed, or send it back afterwards, which is a return. Both release the funds to the source account, but they happen at different times and need different handling.

Failed versus returned

Detail	Failed	Returned
When	Before delivery	After delivery, usually within 2 business days
Status	`failed`	`returned` (was `paid`)
Event	`payout.failed`	`payout.returned`
Typical cause	Invalid account, rail unavailable, compliance block	Account closed, no account, insufficient funds on the receiving side

On both outcomes the pending hold on the source account is released, or reversed if it had been posted, so the amount returns to your available balance. You do not need to write a correcting transaction yourself.

Reading the reason

Both events include a failure object:

{
  "id": "pay_01JA6D4H2K",
  "status": "returned",
  "failure": {
    "code": "account_closed",
    "network_code": "R02",
    "message": "The receiving account has been closed.",
    "returned_at": "2026-09-19T14:05:44Z"
  }
}

code is a stable Ledgerline value you can branch on. network_code is the raw ACH return code or SEPA reason code, useful when you talk to the recipient's bank.

Common return codes

Ledgerline code	ACH code	Meaning	What to do
`insufficient_funds`	R01	The receiving account cannot accept the entry, or an offsetting debit failed.	Retry later or ask the recipient.
`account_closed`	R02	The account is closed.	Collect new bank details and create a new bank account.
`no_account`	R03	The account number does not exist.	Verify details with the recipient.
`invalid_account_number`	R04	The account number is malformed.	Correct the number.
`account_frozen`	R16	The receiving account is frozen.	Contact the recipient.
`compliance_hold`	none	A sanctions or fraud screen blocked the payment.	Do not retry. Review the counterparty.

Timing

On ACH, returns arrive within 2 business days after the payout reaches paid. For that window, treat paid as "delivered, not yet final". If your product releases goods or marks an invoice settled, wait for the window to close or accept the small risk.

Wires and instant rails are final once paid. A recipient has to send the money back voluntarily.

Handling a failure in your application

Listen for payout.failed and payout.returned.
Look up the failure.code.
If the cause is a bad account, mark the counterparty's bank account as invalid in your system so you stop paying into it.
Create a new bank account on the counterparty and verify it.
Create a new payout with a new Idempotency-Key. Reusing the old key would return the failed result.

Warning

Never retry a failed payout with the same idempotency key. Ledgerline stores the original 4xx or 2xx result for 24 hours and replays it. Generate a fresh key for a deliberate second attempt. See Idempotency.

Failures at request time

Some problems stop a payout from being created at all. These return an HTTP error instead of a failed payout:

Code	Status	Cause
`insufficient_funds`	422	The source account's available balance is too low.
`counterparty_unverified`	422	The bank account has not been verified.
`limit_exceeded`	422	The amount is above a per-payout or daily limit.
`rail_unavailable_for_recipient`	422	The receiving bank does not support the chosen rail.
`kyb_required`	403	Your business verification is not approved.

The full list is in Error format and codes with fixes in Troubleshooting common errors.

Reconciling returns

A return appears in your statements as a separate line dated when the bank booked it. Reconciliation matches it to the original payout automatically using the trace number. See Reconciliation.