> ## Documentation Index > Fetch the complete documentation index at: https://developers.uqpay.com/llms.txt > Use this file to discover all available pages before exploring further. # Error codes > The Stablecoin Account API error envelope, status codes, and how to recover from each. [Stablecoin Account API Publisher Disclaimer](/stablecoin-account/v1.6/guide/stablecoin-account-api-publisher-disclaimer) When a Stablecoin Account API call fails, the response carries a non-2xx `code` and a human-readable `message` in the same envelope as success responses: ```json theme={null} { "code": 422, "message": "Insufficient balance" } ``` | Field | Meaning | | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `code` | Mirrors the HTTP status. Branch on it for coarse handling. | | `message` | Human-readable description of what went wrong. Safe to log; branch on it for finer-grained handling, but do not surface it verbatim to end users. | Successful calls always return `code: 200` — check it even on HTTP 200 responses. ## Status codes | `code` | Meaning | What to do | | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `400` | Bad request — a required parameter is missing or a value failed validation. | Fix the request. The `message` names the offending field or rule (for example the Travel Rule validation errors listed below). | | `401` | Unauthorized — no valid token provided, or the token expired. | Request a new access token via [Access Token](/account-center/v1.6/api-reference/access-token) and retry with a fresh `x-auth-token` header. | | `403` | Forbidden — the token lacks permission for this operation or account. | Check the `x-on-behalf-of` header targets a sub-account you can act for; otherwise contact your UQPAY solutions engineer about the missing permission. | | `404` | Not found — the requested resource does not exist. | Check the `order_id` or `address_id`; note that some lookups accept only the long UUID form. | | `409` | Conflict — usually an idempotency collision: the same `x-idempotency-key` was used with a different request, or the original request is still processing. | Reuse the key only for exact retries of the same request. If the first request may still be in flight, wait and query the resource instead of resubmitting. | | `422` | Unprocessable — the request is well-formed but violates a business rule, for example `Insufficient balance`. | Resolve the business condition (top up the balance, raise the amount above the minimum, refresh an expired quote) and resubmit. | | `500` | Internal error. | Retry with the same `x-idempotency-key` so a retry cannot double-create the order. If it persists, contact support with the `x-response-id` response header. | Every response includes an `x-response-id` header (UUID). Log it — UQPAY support uses it to trace the exact request. ## Business rule errors to expect These `message` values indicate conditions your integration should handle deliberately rather than treat as generic failures: | Message | Trigger | Recovery | | ----------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `Insufficient balance` | The selling/withdrawal amount exceeds `available_balance`. | Check [Retrieve Asset](/stablecoin-account/v1.6/api-reference/retrieve-asset) before submitting; remember in-flight orders hold funds in `frozen_balance`. | | `missing travel_rule_data for binance withdraw` | [Create Withdraw](/stablecoin-account/v1.6/api-reference/create-withdraw) to a Binance-routed destination whose address book entry has no Travel Rule data. | Backfill `meta_data` via [Update Address Book](/stablecoin-account/v1.6/api-reference/update-address-book), then resubmit. See [Travel Rule compliance](/stablecoin-account/v1.6/guide/travel-rule-compliance). | | `invalid wallet_type` / `invalid address_party` / `invalid entity_type` | A `meta_data` object with a value outside the allowed enums. | Use the exact values from the [Travel Rule field reference](/stablecoin-account/v1.6/guide/travel-rule-compliance#field-reference). | | `individual third party requires first_name and last_name` | Third-party individual beneficiary missing name fields. | Collect and resubmit the missing beneficiary fields. | | `corporation third party requires company_name` | Third-party corporate beneficiary missing the company name. | Collect and resubmit the missing beneficiary fields. | | `third party requires country and city` | Third-party beneficiary missing location fields. | Populate from [List Countries](/stablecoin-account/v1.6/api-reference/list-countries) and [List Regions](/stablecoin-account/v1.6/api-reference/list-regions). | | `hosted wallet requires vasp_id or vasp_name` | Hosted wallet `meta_data` without VASP identification. | Look up the VASP via [List VASPs](/stablecoin-account/v1.6/api-reference/list-vasps), or supply the exchange name as `vasp_name`. | ## Failures after acceptance A `code: 200` response means the order was **accepted**, not that it will succeed. Deposits, withdrawals, conversions, and transfers can still end in `Failed` (or `Submit Failed`) asynchronously — watch the corresponding webhook (`ramp.*.failed` events) and treat the order's `message` field as the failure reason where present. ## Related * [Core concepts](/stablecoin-account/v1.6/guide/core-concepts) — the response envelope and idempotency * [Travel Rule compliance](/stablecoin-account/v1.6/guide/travel-rule-compliance) * [Testing in sandbox](/stablecoin-account/v1.6/guide/testing-in-sandbox) — exercising error paths before go-live