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

# Settlement failures

> Fix settlement error codes in your request, and route operational holds to a person.

A rejected request moved no money and returns an error code you fix. A settlement that started and did not finish is held, in full, and reported by name on the payment.

| Where | What you get | Who acts |
| - | - | - |
| Before anything exists | An error code on your request | You |
| After settlement started | An operational state on the payment | Stableyard, usually |

## Fix these error codes in your request

| Code | HTTP | Meaning | What to do |
| - | - | - | - |
| `settlement_profile_required` | 422 | Returned by `POST /v2/payments` when the receiving account has no settlement profile, **or** its profile no longer resolves to an active destination backed by an active wallet | Check the account's destinations rather than assuming nothing was set. Set a profile, then replay the create with the same idempotency key |
| `settlement_not_ready` | 409 | Settlement has not reached the state this operation needs. Typically a refund arriving after merchant settlement or fee payout has begun | Read the payment. If settlement has started, a partner-created refund is no longer the route, and the return is handled as a recovery |
| `settlement_already_exists` | 409 | A settlement operation for that payment is already created, signing, broadcast or under review | Do not create a second one. Read the payment and wait for the first to resolve |
| `payment_method_not_supported` | 422 | The chosen destination cannot receive settlement | Select a crypto destination with `capabilities.settlementSupported: true` |

Stableyard refuses to create a receiving object it cannot deliver from, rather than holding the money. [Settlement destinations](/settlement/destinations) covers listing and setting a destination, and [Errors](/errors) lists every code with its HTTP status.

## A destination change never re-routes money

| Situation | What happens |
| - | - |
| The preferred destination is disabled | The disable is refused. Select a different active destination first |
| A bank or rail destination is selected | Refused. It returns `settlementSupported: false` with an `unavailableReason` such as `linked_bank_receive_settlement_not_enabled` or `bank_settlement_provider_not_configured` |
| The destination changes after a payment was created | Nothing re-routes. Every payment and every detected deposit snapshots the destination in force when it was created |

That last row is the safety property: a settings change cannot redirect money already on its way.

## A payout that fails after funding recovers to the frozen crypto destination

For an outbound leg, `offrampStatus` distinguishes a failure that cost nothing from one that did.

```mermaid theme={null}
flowchart LR
  A["Funds collected"] --> B["Payout attempted"]
  B --> C["Terminal failure after funding"]
  C --> D["Recovery to the frozen crypto destination"]
```

| `offrampStatus` | What it means |
| - | - |
| `not_started` | Funding was never confirmed. Nothing was collected and no recovery applies |
| `failed` | A verified terminal payout failure **after** confirmed funding |
| `refunding` | A recovery is reserved against the sending account's frozen preferred crypto settlement destination |
| `refunded` | That recovery settled and is confirmed |

A failure before funding is confirmed is not a failed payout. Create a new payment with a fresh quote; do not raise it as a recovery.

<Warning>
  A recovery settles to the preferred crypto destination frozen at the moment it is reserved. If the sending account has no active preferred crypto destination, no recovery starts and it waits for a person. Keeping one on every paying account is your obligation, not a default.
</Warning>

## `requires_intervention` goes to a person

`operationalState` is a separate axis from `status`: a payment can be `accepted` and healthy, or `accepted` and stopped. Which of these states you can meet depends on the capabilities switched on for your app.

| `operationalState` | `operationalReasonCode` | What it means |
| - | - | - |
| `retrying` | `settlement_retry_scheduled` | Automation is still working. No action |
| `requires_intervention` | `settlement_unconfirmed` | Settlement was submitted and confirmation has not arrived |
| `requires_intervention` | `settlement_failed` | Settlement to the destination failed |
| `requires_intervention` | `settlement_requires_intervention` | Automation stopped for review |

Deposits carry the same idea: `status: requires_intervention` on the deposit, and `settlement.status: requires_intervention` with a `reasonCode` naming why. Raw provider errors are never exposed there.

**Financial status is preserved through all of this.** An `accepted` or `succeeded` payment does not regress because an operational field changed; if your records can move an order backwards out of a fulfilled state on an operational event, the model is wrong.

| You do | A person does |
| - | - |
| Fix a missing or invalid settlement destination, then replay | Resolve any `requires_intervention` state |
| Read the payment instead of retrying blindly | Decide what happens to funds held after a failure |
| Put a held payment in a queue in front of a named operator | Release a settlement stuck unconfirmed |
| Keep a preferred crypto destination on every paying account | Reserve and confirm a post-funding recovery |

<Warning>
  Never create a replacement payment to work around a stuck one. Reuse the original payment and its idempotency key. A second payment for the same obligation is how a recipient gets paid twice.
</Warning>

<Card title="Next: Settlement webhooks and testing" icon="bell" href="/settlement/platform-tools">
  The events to act on, and the cases to rehearse in sandbox.
</Card>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.