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

# 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

An inbound transfer was sent back before Conduit could credit it to the customer. The transaction is in a terminal `failed` state.

One code covers two situations, and **they do not look the same on the wire**. What decides it is where the money was headed, not which rail it arrived on:

| Case                                                                                                         | Where the deposit was headed                  | `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) | your customer's own virtual account or wallet | `returned_by_sender`                         |
| [A funding transfer was sent back](#case-2-a-funding-transfer-was-sent-back)                                 | a funding address on a deposit-funded order   | **absent**                                   |

Read the case that matches where the funds were going. Branching on `failureCode` alone works for the first 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_abc123",
  "correlationId": "corr_xyz789",
  "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

<Warning>
  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.
</Warning>

**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"
```

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_abc123",
  "type": "deposit",
  "status": "failed",
  "failureMessage": "This transaction could not be completed. Contact support if this persists."
}
```

<Warning>
  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.
</Warning>

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_ret1",
      "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_abc123",
      "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.

## 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** -- neither case is recoverable by retrying the original transfer; a new transfer from the sender is required

## 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_abc123",
    "failureCode": "returned_by_sender"
  }
}
```

On a funding-address transfer it does not, on either rail:

```json theme={null}
{
  "type": "transaction.failed",
  "data": {
    "transactionId": "txn_abc123",
    "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