{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-products/hosted-checkout/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Error Codes","description":"Official Banxa API documentation – on-ramp and off-ramp transfers with identity verification and compliance.","llmstxt":{"title":"Banxa Developer Documentation","description":"Integrate crypto-fiat exchange with Banxa's licensed infrastructure: payments, KYC, compliance, and settlement handled. 150+ countries, 45 global licences.","details":{"content":"Two integration products: **Banxa Native API** for partners who manage their own KYC and want full UX control (headless, HMAC server-to-server, no Banxa-hosted screens); **Banxa Hosted Checkout** for partners who want Banxa to handle KYC and payments (three paths: Referral URL, API, or React Native SDK). Both use the same sandbox and production environments at `https://api.banxa-sandbox.com` and `https://api.banxa.com`.\n\n## Constraints\n\n- **Authentication**: HMAC credentials must be stored server-side only, never expose in frontend, mobile, or client-side code. HMAC is required for all Native API calls and for KYC sharing in Hosted Checkout; `x-api-key` is used for all other Hosted Checkout endpoints.\n- **`externalCustomerId`**: Required on every buy and sell order. Use a stable opaque identifier, never PII.\n- **`identityReference`**: Must remain constant for the same user across all requests. Must not contain PII. If you attempt to create an identity for an email that already exists, you will receive a 422 / code 81, so retrieve the existing record rather than retrying creation. Use `GET /eapi/v0/identities/{identityReference}?email=user@example.com` to look up the real `identityReference` linked to an email.\n- **`quoteId`**: Only supported by `POST /eapi/v0/ramps` (bank transfer). The React Native SDK and Embedded Payment Button do not accept a `quoteId`, so use indicative pricing (`GET /eapi/v0/price`) for SDK and Embedded Payment Button flows.\n- **Quotes**: Indicative prices are not rate-locked, so refresh close to order creation to minimise rate drift. Locked quotes (`GET /eapi/v0/quote`) expire after approximately 3 minutes and are only valid for bank transfer ramp creation.\n- **Eligibility gate**: Never create a ramp or invoke the SDK when `paymentReady` is `false`. Always check eligibility and satisfy all requirements before payment execution.\n- **Webhooks**: Verify all inbound webhook signatures with HMAC-SHA256 before processing. Return HTTP 200 immediately and process asynchronously.\n- **Product selection**: Banxa Native is for partners who manage their own KYC. Banxa Hosted Checkout is for partners who do not do KYC. These are separate products with separate flows: do not mix endpoints across products.\n- **SDK scope**: The React Native SDK has no `banxa.customerIdentity` module. Identity and KYC are handled through the Native API only. `primerCallbacks` and `primerSettings` are Native context only and must not be referenced in Hosted Checkout integrations.\n- **Payment method naming**: Never use \"eAPI\" or \"EAPI\" as a product name. The correct name is \"Banxa Native API\". The URL path prefix `/eapi/` is correct and should not be changed.\n"},"hide":false,"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"error-codes","__idx":0},"children":["Error Codes"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Common error responses from the Banxa Hosted Checkout API, what they mean, and how to resolve them."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"http-status-codes","__idx":1},"children":["HTTP status codes"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"HTTP status"},"children":["HTTP status"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Meaning"},"children":["Meaning"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Request failed validation or a required feature is not enabled. Check the error ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}," in the body."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Authentication failed. Wrong key type, wrong environment, or missing HMAC signature."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["422"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The request was well-formed but cannot be processed. Check the error ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}," in the body."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Rate limit exceeded. Sandbox: 120 requests per minute per merchant account. Production: 500 requests per minute per IP. Back off and retry; prefer webhooks over polling."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["5xx"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Banxa-side error. Retry with backoff; contact support if persistent."]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"application-error-codes","__idx":2},"children":["Application error codes"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Code"},"children":["Code"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Message"},"children":["Message"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Cause and resolution"},"children":["Cause and resolution"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["4002"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Validation error"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A field in the payload failed backend validation. A common cause is ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," values in address or identity fields: optional fields must be a string or omitted entirely, never ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["4005"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The feature is not enabled"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The endpoint you are calling (most commonly KYC sharing) is not enabled on your account for this environment. Enablement requires a compliance review; contact your account manager."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["5034"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Coin restriction"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The requested crypto asset is not available for the customer's region. For example, stablecoins are not available to customers in Canada."]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"authentication-errors","__idx":3},"children":["Authentication errors"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Symptom"},"children":["Symptom"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Cause"},"children":["Cause"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}," on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/v2"]}," endpoints"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Using sandbox credentials against production (or vice versa), or a malformed ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-api-key"]}," header. The correct base URL per environment is shown in the merchant dashboard."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}," on ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /v2/identities/token/share"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["This endpoint uses HMAC authentication, not ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-api-key"]},". Sign the request with your HMAC key pair. See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/hosted-checkout/docs/getting-started/authentication-and-environments"},"children":["Authentication & Environments"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Webhook signature verification failing"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Verify with your HMAC secret, not the v2 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-api-key"]},". See ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/products/hosted-checkout/docs/transaction-lifecycle/webhooks#securing-webhooks"},"children":["Webhooks"]},"."]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"checkout-errors","__idx":4},"children":["Checkout errors"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Symptom"},"children":["Symptom"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Cause"},"children":["Cause"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["checkoutUrl"]}," no longer loads"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["The checkout URL is valid for 1 minute from order creation and must be loaded within that window (once loaded, it does not expire). Create the order when the customer confirms and open the URL immediately."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["CSRF token mismatch"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Stale checkout session, usually from reusing an old URL or a cached page. Have the customer refresh the page or retry; if it persists, create a fresh order."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If you encounter an error code not listed here, contact your integration manager with the full response body and a trace ID if one is present."]}]},"headings":[{"value":"Error Codes","id":"error-codes","depth":1},{"value":"HTTP status codes","id":"http-status-codes","depth":2},{"value":"Application error codes","id":"application-error-codes","depth":2},{"value":"Authentication errors","id":"authentication-errors","depth":2},{"value":"Checkout errors","id":"checkout-errors","depth":2}],"frontmatter":{"title":"Error Codes | Banxa Docs","description":"Banxa Hosted Checkout API error code reference: 4002 validation errors, 4005 feature not enabled, 5034 asset restrictions, 401 authentication failures, and checkout URL expiry.","seo":{"title":"Error Codes"}},"lastModified":"2026-07-28T01:09:56.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/products/hosted-checkout/docs/reference/error-codes","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}