Errors - Wayex API

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

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

Always log the requestId from failed responses. It is the fastest way for support to trace exactly what happened.

​Status codes

​Common Treasury codes

​Treasury operation statuses

Status codes

Common Treasury codes

Treasury operation statuses