Errors - Sakawave API

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.

{
  "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.

{
  "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.