> ## Documentation Index
> Fetch the complete documentation index at: https://docs.conduit.financial/llms.txt
> Use this file to discover all available pages before exploring further.
# RETURNED_BY_SENDER error
> An inbound transfer was sent back before it could be credited — the code is present on a deposit to your customer's own account, and withheld on a transfer into a funding address
## What happened
A transfer was sent back by a bank. The transaction is in a terminal `failed` state.
One code covers three situations, and **they do not look the same on the wire**. What decides it is where the money was headed and whether it had already settled, not which rail it arrived on:
| Case | What happened | `failureCode` on the transaction and webhook |
| ---------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | -------------------------------------------- |
| [The deposit was sent back before it was credited](#case-1-the-deposit-was-sent-back-before-it-was-credited) | inbound transfer to your customer's own virtual account or wallet, returned before Conduit credited it | `returned_by_sender` |
| [A funding transfer was sent back](#case-2-a-funding-transfer-was-sent-back) | transfer to a funding address on a deposit-funded order, returned before or after credit | **absent** |
| [A completed transfer was returned after settlement](#case-3-a-completed-transfer-was-returned-after-settlement) | a deposit or payout that had already reached `completed`, returned by a bank days later | `returned_by_sender` |
Read the case that matches where the funds were going and whether the transfer had settled. Branching on `failureCode` alone works for the first and third and never fires for the second — on either rail.
## Case 1: the deposit was sent back before it was credited
A deposit headed for your customer's own virtual account or wallet was sent back to where it came from before Conduit credited it — either because the sending institution reversed it, or because it was returned during review.
```json theme={null}
{
"type": "RETURNED_BY_SENDER",
"title": "Returned by sender",
"status": 422,
"detail": "The inbound transfer was returned by the sender's institution, or compliance marked the deposit as returned before credit. The deposit was not credited.",
"resolution": "Contact the sender's bank or Conduit support for the return reason. The customer can attempt the transfer again from the source after the issue is resolved.",
"docs": "/errors#returned-by-sender",
"instance": "/v2/transactions/txn_034A0gCCVmVhsfuR8SfVwM",
"correlationId": "00469ea4-52c1-4ffa-bd05-9f28b236a5fe",
"timestamp": "2026-01-15T09:30:00.000Z"
}
```
### Common causes
* **Insufficient funds at the originating institution** -- the sender's account did not have sufficient funds when the transfer was processed
* **Account closed or invalid** -- the originating account was closed or the transfer details were invalid
* **Sender-initiated reversal** -- the sender requested a recall or reversal of the transfer before it cleared
### Recovery
This is a terminal state. No funds were credited to the customer. The customer
should contact the sender or their own financial institution for details on
the return.
**1. Confirm the terminal state**
```bash theme={null}
curl -X GET https://api.conduit.financial/v2/transactions/txn_034A0gCCVmVhsfuR8SfVwM \
-H "x-api-key: YOUR_API_KEY"
```
The response shows `status: "failed"` and `failureCode: "returned_by_sender"`.
**2. Notify the customer**
The inbound transfer was not credited. The customer should be informed that the transfer was returned and that they should contact the sender for the return reason and next steps.
**3. Do not resubmit on behalf of the sender**
The original transfer is gone: it went back to where it came from, and neither Conduit nor the customer can recall it. A new transfer from the sender is required.
## Case 2: a funding transfer was sent back
A transfer arrived at a [funding address](/concepts/deposit-funded-orders) — the address a deposit-funded order publishes — and was sent back to the address it came from.
The deposit ends in `status: "failed"` with a neutral `failureMessage` and **no `failureCode`**:
```json theme={null}
{
"id": "txn_034A0gCCVmVhsfuR8SfVwM",
"type": "deposit",
"status": "failed",
"failureMessage": "This transaction could not be completed. Contact support if this persists."
}
```
Conduit reports every terminal at a funding address the same way, whichever
direction it happened in and whatever caused it. The absence of a
`failureCode` is not itself a signal, and no field distinguishes one cause
from another. Do not write code that reads meaning into which fields are
present.
On a `failed` deposit, `funded`, `returned` and `available` are all absent too — so the deposit alone does not tell you where the money went.
### Common causes
* **The sending address was not registered** -- the transfer came from an address that is not a [registered address](/concepts/registered-addresses) on the customer, so it was not accepted
* **No order claimed the transfer** -- nothing was waiting for the funds, or the order it was meant to fund had already expired
* **The transfer could not be accepted** -- it was not eligible to be credited
### How to reconcile
Do not branch on `failureCode`. Reconcile against the order and against the return transaction instead.
**1. Read the order the transfer was meant to fund**
The order reports its own outcome. A transfer that is not accepted never funds anything, so the order cannot reach its total and expires at its deadline.
**2. Find the return transaction**
Money sent back is its own transaction, `type: "deposit_return"`, carrying `returnOf` — the id of the deposit it returns:
```bash theme={null}
curl -X GET "https://api.conduit.financial/v2/transactions?type=deposit_return" \
-H "x-api-key: YOUR_API_KEY"
```
```json theme={null}
{
"data": [
{
"id": "txn_034A1PiBqxWhdd9FzcAcfm",
"customerId": "cus_033XCUGHvwYcNcNUAqBZYq",
"type": "deposit_return",
"status": "completed",
"stage": "settled",
"source": {
"type": "deposit_address",
"address": "0xd378c2A6D8fAEeCB96E38507a0688694d2ee823E",
"assetAmount": {
"code": "USDC",
"chain": "polygon",
"amount": "1.500000"
}
},
"destination": {
"type": "external_crypto",
"address": "0x778834eE81d38c6acAf40CC75b1e167334d3361C",
"txHash": "0x473b80f44fcd1801ddd945c85f78af17528f2eff10190540bec296625bd96bf2",
"assetAmount": {
"code": "USDC",
"chain": "polygon",
"amount": "1.500000"
}
},
"returnOf": "txn_034A0gCCVmVhsfuR8SfVwM",
"createdAt": "2026-07-30T09:31:00.000Z",
"updatedAt": "2026-07-30T09:34:00.000Z"
}
],
"meta": {
"mode": "cursor",
"nextCursor": null,
"previousCursor": null,
"total": 1
}
}
```
Match `returnOf` to your deposit's id. Once the return is `completed`, `destination.txHash` is the on-chain hash of the refund, so you can verify it on chain and tie it to your own records.
`returnOf` is present whenever Conduit can still resolve the deposit a return came from, so a return with no `returnOf` is not evidence about your deposit either way. If you find no return naming your deposit, match on the sending address and amount instead, and contact support if it stays unclear — do not read the absence as proof that nothing was sent back.
**3. Tell the customer what to do next**
If the sending address was not registered, register it and have the customer send again. Contact support if the deposit keeps failing.
## Case 3: a completed transfer was returned after settlement
A transfer that had already reached `completed` — a deposit into your customer's virtual account, or a payout to a recipient — was returned by a bank days later: the wire was recalled, the ACH credit was returned, or, for a payout, the recipient's bank could not apply it. This is rare — most returns happen before credit (Case 1) — but it can happen on any completed fiat transfer.
The transaction flips straight from `completed` to `failed`:
```json theme={null}
{
"id": "txn_034A0gCCVmVhsfuR8SfVwM",
"type": "deposit",
"status": "failed",
"failureCode": "returned_by_sender",
"failureMessage": ""
}
```
**For a returned deposit**, the funds that were briefly available are removed from the balance. Contact the sender for the return reason; a new transfer is required to receive the funds again.
**For a returned payout**, Conduit may issue a replacement payout once the return is resolved. The replacement carries `retryOf`, the id of the original payout it replaces:
```json theme={null}
{
"id": "txn_034A1PiBr90RuHwUoGstRU",
"type": "withdrawal",
"status": "pending",
"retryOf": "txn_034A0gCCVmVhsfuR8SfVwM"
}
```
`retryOf` is absent on every payout that is not a replacement, and not every returned payout gets one — Conduit resolves each return individually. You learn about a replacement the same way you learn about the original: its own `transaction.created` / `transaction.completed` webhooks, carrying `retryOf`.
### Recovery
This is a terminal state on the original transfer. No action you take reopens
it. Wait for a replacement payout, if one is issued, or contact support for
the return reason.
**1. Confirm the terminal state**
```bash theme={null}
curl -X GET https://api.conduit.financial/v2/transactions/txn_034A0gCCVmVhsfuR8SfVwM \
-H "x-api-key: YOUR_API_KEY"
```
The response shows `status: "failed"`, `failureCode: "returned_by_sender"`, and a `failureMessage` naming the bank's own reason when it sent one.
**2. For a payout, watch for a replacement**
A replacement payout's own webhooks carry `retryOf` pointing back at `txn_034A0gCCVmVhsfuR8SfVwM`. There is no separate endpoint to look one up — react to the webhook.
## Prevention
* **Handle `transaction.failed` by where the deposit was headed** -- for a deposit into your customer's own virtual account or wallet, branch on `failureCode === 'returned_by_sender'`. For a transfer into a funding address that branch never runs on either rail: key off `type` and `status`, then look for the paired `deposit_return`
* **Register sending addresses before the customer sends** -- see [registered addresses](/concepts/registered-addresses)
* **Do not retry automatically** -- none of the three cases is recoverable by retrying the original transfer; a new transfer from the sender is required, or Conduit issues a replacement payout itself (Case 3)
## Related webhooks
`transaction.failed` fires when the return is recorded. On a deposit into your customer's own account it carries the code:
```json theme={null}
{
"type": "transaction.failed",
"data": {
"transactionId": "txn_034A0gCCVmVhsfuR8SfVwM",
"failureCode": "returned_by_sender"
}
}
```
On a funding-address transfer it does not, on either rail:
```json theme={null}
{
"type": "transaction.failed",
"data": {
"transactionId": "txn_034A0gCCVmVhsfuR8SfVwM",
"failureMessage": "This transaction could not be completed. Contact support if this persists."
}
}
```
The return itself emits its own `transaction.created` and `transaction.completed`, and the completed event carries the same `destination.txHash` as the read.
## Related endpoints
* [GET /v2/transactions/:id](/api-reference/transactions/get-a-transaction-by-id) -- read transaction state
* [GET /v2/transactions](/api-reference/transactions/list-transactions) -- filter with `type=deposit_return` to find a return
* [Deposit-funded orders](/concepts/deposit-funded-orders) -- how funding addresses, returns and the rolled-up fields work
* [Registered addresses](/concepts/registered-addresses) -- registering the addresses a customer may send from