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

# Errors

> Handle Sakawave error envelopes and machine-readable codes.

Use the HTTP status for the error class, `code` for program logic, and `message` for logs or operator-facing context. Do not branch on `message` text.

```json theme={null}
{
  "statusCode": 409,
  "message": "The FX quote amount does not match this transfer.",
  "code": "fx_quote_amount_mismatch"
}
```

Some framework-produced errors may omit `statusCode`; always read the HTTP response status.

## Validation errors

Validation returns all detected failures with both a dotted `field` and raw `path`.

```json theme={null}
{
  "statusCode": 400,
  "message": "2 fields failed validation.",
  "code": "validation_failed",
  "errors": [
    {
      "message": "Must be a valid identifier.",
      "field": "sourceAccountId",
      "code": "custom",
      "path": ["sourceAccountId"]
    }
  ]
}
```

## Observed public codes

The following codes are present in current public-route execution paths. Their stability still requires API engineering approval.

| Area | Codes |
| - | - |
| Authentication | `INVALID_API_KEY`, `api_key_required` |
| Rate limiting | `api_key_rate_limit_exceeded`, `api_key_rate_limit_unavailable` |
| Customers | `customer_not_found`, `customer_already_exists`, `customer_fields_do_not_match_type` |
| Accounts | `account_not_found`, `customer_not_found`, `client_details_incomplete`, `system_account_type_reserved` |
| Destinations | `recipient_not_found`, `transfer_destination_expired`, `destination_field_required`, `route_country_mismatch`, `tag_belongs_to_client` |
| FX | `fx_quote_not_found`, `fx_quote_amount_too_small`, `fx_quote_amount_out_of_range`, `invalid_fx_quote`, `fx_provider_unavailable` |
| Transfers | `transfer_not_found`, `transfer_source_account_ineligible`, `transfer_destination_unavailable`, `destination_currency_mismatch`, `destination_route_mismatch`, `same_transfer_account`, `fx_quote_required`, `fx_quote_mismatch`, `fx_quote_amount_mismatch`, `fx_quote_unavailable`, `insufficient_funds` |
| Transactions | `transaction_not_found`, `account_not_found` |

## Retry decisions

* Do not retry `400`, `401`, `403`, `404`, or `409` without changing state or input.
* Retry `429` after `retryAfterSeconds` with jitter.
* Retry transient `5xx` responses with capped exponential backoff.
* For an uncertain transfer creation result, retrieve by your persisted `externalReference` workflow or safely repeat the same request with the same reference. Never generate a new reference merely because the first response was lost.

Log the response `X-Request-ID`, your external reference, status, and error code. Never log authorization headers or unmasked identity and bank fields.


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