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

# Errors

> The standard error envelope and what each status code means.

Wayex uses conventional HTTP status codes and returns a consistent JSON error envelope on every failure.

```json theme={null}
{
  "type": "authentication_error",
  "code": "missing_api_key",
  "message": "A human-readable explanation of what went wrong",
  "requestId": "req_e43037e6-8149-4297-9a94-9bcf11a59dbb"
}
```

| Field       | Description                                                                       |
| ----------- | --------------------------------------------------------------------------------- |
| `type`      | The error category (e.g. `validation_error`, `authorization_error`, `not_found`). |
| `code`      | A stable, machine-readable code you can branch on.                                |
| `message`   | A human-readable explanation. Do not parse this — use `code`.                     |
| `requestId` | The unique id for this request. **Include it when contacting support.**           |

## Status codes

| Status        | Meaning                                                                                                                             |
| ------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `200` / `201` | Success.                                                                                                                            |
| `400`         | Malformed request.                                                                                                                  |
| `401`         | Missing or invalid API key.                                                                                                         |
| `403`         | Authenticated, but not allowed to perform this action.                                                                              |
| `404`         | The resource does not exist (or is out of your scope).                                                                              |
| `409`         | Conflict — e.g. an illegal state transition, or an `Idempotency-Key` reused with different parameters (`idempotency_key_conflict`). |
| `422`         | Validation failed (a semantically invalid value, e.g. a developer fee above the cap).                                               |
| `429`         | Rate limited — slow down and retry with backoff.                                                                                    |
| `5xx`         | A Wayex-side error. Safe to retry idempotent requests with backoff.                                                                 |

## Common Treasury codes

| Code                              | Status | Meaning                                                                                             |
| --------------------------------- | ------ | --------------------------------------------------------------------------------------------------- |
| `treasury_configuration_required` | `409`  | This tenant account has no effective Treasury configuration. Contact Wayex before retrying.         |
| `sumsub_evidence_required`        | `403`  | The payout does not have current accepted KYC evidence.                                             |
| `sumsub_token_invalid`            | `422`  | Sumsub could not accept the single-use share token. Request a fresh token for this beneficiary.     |
| `insufficient_balance`            | `422`  | This account's wallet has insufficient available funds after existing reservations.                 |
| `asset_network_unavailable`       | `422`  | The asset/network is not enabled for this account and available at runtime.                         |
| `quote_expired`                   | `409`  | The Treasury conversion quote expired before acceptance. Create a new quote.                        |
| `sumsub_provider_unavailable`     | `502`  | Reusable-KYC validation is temporarily unavailable. Retry the same idempotent request with backoff. |
| `destination_screening_required`  | `422`  | The stablecoin destination is not yet eligible for withdrawal. Use an active validated destination. |

## Treasury operation statuses

| Status      | Meaning                                                                                                                                         |
| ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| `accepted`  | KYC and policy checks passed and the source amount was durably reserved. Provider submission may still be pending or have an unknown outcome.   |
| `held`      | The effective manual-review or threshold policy requires operator approval before the operation can continue.                                   |
| `submitted` | Funds remain reserved and the bank or blockchain instruction was submitted. This is not settlement.                                             |
| `settled`   | The downstream bank or blockchain leg completed and the reservation was captured.                                                               |
| `failed`    | The operation did not complete. Inspect wallet movements to confirm the reservation release or any recovery action.                             |
| `returned`  | A previously submitted or settled payout was returned. The effective return-loss policy determines the client credit and any recovery exposure. |

Some responses also include more specific settlement detail or a `nextAction`. An unknown or
reconciling external outcome is not a failure: keep the original operation and reservation intact
until its real outcome is established. See
[Operations and reconciliation](/treasury/operations-and-reconciliation).

<Note>
  Always log the `requestId` from failed responses. It is the fastest way for support to trace
  exactly what happened.
</Note>