Errors

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 — honor the `Retry-After` header, then retry with backoff. See Rate limits.
`5xx`	A Wayex-side error. Safe to retry idempotent requests with backoff.

Rate limits

Each API key is a token bucket, not a fixed window: it refills continuously at a sustained rate of 25 requests/second and can hold up to 50 requests of burst capacity (defaults — your account may be configured differently). A request spends one token; an empty bucket returns 429 until the bucket refills. Responses include three headers you can use to pace your integration:

Header	Meaning
`X-RateLimit-Limit`	The bucket’s burst capacity (the largest instantaneous burst it admits).
`X-RateLimit-Remaining`	How many tokens remain in the bucket right now.
`X-RateLimit-Reset`	Seconds until the bucket refills to full capacity at the sustained rate — not a timestamp.

Exceeding the limit returns 429 with code rate_limited and a Retry-After header (in seconds). Wait at least that long, then retry with backoff.

Common API codes

Code	Status	Meaning
`idempotency_key_required`	`400`	The write is missing its `Idempotency-Key` header. See Idempotency.
`unsupported_asset_network`	`400`	The asset does not settle on the requested network, or Wayex cannot send or receive it there. Choose another network — this is not transient.
`invalid_request`	`400`	The body failed schema validation. One case worth coding for: free-form maps reject the reserved key `@@wxtype` (and any `@@wxtype.esc…` variant). See Reserved metadata key.
`secret_key_required`	`403`	A publishable key was used on an endpoint that requires a secret key.
`insufficient_scope`	`403`	The API key’s scope list does not include the scope this endpoint needs. The message names the scope.
`ip_not_allowed`	`403`	The request came from outside the key’s `allowedIps` networks.
`step_up_required`	`403`	The action needs a recent second-factor (MFA) confirmation from a console session. Re-confirm and retry.
`idempotency_key_conflict`	`409`	The `Idempotency-Key` was reused with different parameters. Use a fresh key for a different request.
`idempotency_key_in_progress`	`409`	The original request with this key is still executing. Honor `Retry-After`, then retry with the same key.
`rate_limited`	`429`	Too many requests this second. Honor `Retry-After`, then retry 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.
`settlement_network_required`	`400`	A conversion quote from AUD to a stablecoin omitted `settlementNetwork`. Name the chain the stablecoin settles onto.
`conversion_route_conflict`	`409`	The named `settlementNetwork` differs from the settlement route Wayex has pinned for that asset. Use the pinned chain.
`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`	`403`	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 hold reasons

A held operation carries a statusReason naming why it is parked. Show it, and use it to decide whether waiting will help. Most reasons describe a review or capacity condition that Wayex clears; this one describes your request and will not clear on its own:

`statusReason`	Meaning	What to do
`withdrawal_network_not_held`	The stablecoin withdrawal names a network this account has no credited deposit and no settled conversion for. The source debit is reserved; nothing was sent.	Withdraw on a network you have funded, or convert onto that network first. Wayex releases genuine cases.

Treat statusReason as an informational string, not a closed set — new reasons can appear. Branch on status and nextAction, and surface the reason to your operators verbatim.

Reserved metadata key

Free-form maps you send us — metadata on customers and counterparties, and partyContext, businessIdentity, and glMapping on Treasury requests — reserve one key name: @@wxtype, and any @@wxtype.esc… variant of it. Wayex uses it internally to encode stored values. A map containing that key is refused with 400 invalid_request and nothing is written — including on a PATCH that would otherwise merge. Near misses such as wxtype, @@wxtypes, or my@@wxtype are ordinary keys and are accepted. Nothing else about these maps changed.

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

Get started

Treasury guide

Console guide

Status codes

Rate limits

Common API codes

Common Treasury codes

Treasury operation statuses

Treasury hold reasons

Reserved metadata key

​Status codes

​Rate limits

​Common API codes

​Common Treasury codes

​Treasury operation statuses

​Treasury hold reasons

​Reserved metadata key

Status codes

Rate limits

Common API codes

Common Treasury codes

Treasury operation statuses

Treasury hold reasons

Reserved metadata key