Error Codes

For the complete documentation index, see llms.txt. Append .md to any page URL for its markdown version.

Common error responses from the Banxa Hosted Checkout API, what they mean, and how to resolve them.

HTTP status codes

HTTP status	Meaning
`400`	Request failed validation or a required feature is not enabled. Check the error `code` in the body.
`401`	Authentication failed. Wrong key type, wrong environment, or missing HMAC signature.
`422`	The request was well-formed but cannot be processed. Check the error `code` in the body.
`429`	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.
`5xx`	Banxa-side error. Retry with backoff; contact support if persistent.

Application error codes

Code	Message	Cause and resolution
`4002`	Validation error	A field in the payload failed backend validation. A common cause is `null` values in address or identity fields: optional fields must be a string or omitted entirely, never `null`.
`4005`	The feature is not enabled	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.
`5034`	Coin restriction	The requested crypto asset is not available for the customer's region. For example, stablecoins are not available to customers in Canada.

IP binding

These errors come from POST /v2/buy and POST /v2/sell. Unlike the numeric codes above, IP_BINDING_MISSING is a string. See IP Binding.

HTTP status	`code`	What happened	What to do
`422`	`IP_BINDING_MISSING`	IP binding is on for your account and the order had neither `ipBinding` nor `ipBindingOmitted`. The order was not created.	Send `ipBinding` with the customer's IP address, or `ipBindingOmitted` for iCloud Private Relay customers, then create the order again.
`422`	none	An `ipBinding`, `ipBindingOmitted` or `originalUrl` value is invalid. For example: a range whose host part isn't zero (`203.0.113.7/24` instead of `203.0.113.0/24`), two items with the same `family`, or both `ipBinding` and `ipBindingOmitted`.	Fix the field named in `errors` and send the order again.

Example IP_BINDING_MISSING response:

{
  "message": "The ipBinding field is required.",
  "code": "IP_BINDING_MISSING",
  "errors": {
    "ipBinding": [
      "The ipBinding field is required. Send ipBindingOmitted instead only when the customer uses iCloud Private Relay."
    ]
  }
}

Authentication errors

Symptom	Cause
`401` on `/v2` endpoints	Using sandbox credentials against production (or vice versa), or a malformed `x-api-key` header. The correct base URL per environment is shown in the merchant dashboard.
`401` on `POST /v2/identities/token/share`	This endpoint uses HMAC authentication, not `x-api-key`. Sign the request with your HMAC key pair. See Authentication & Environments.
Webhook signature verification failing	Verify with your HMAC secret, not the v2 `x-api-key`. See Webhooks.

Checkout errors

Symptom	Cause
`checkoutUrl` no longer loads	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.
CSRF token mismatch	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.
Checkout shows error `50422` on a sell order	No sell fulfilment flow is configured for your account, or your account uses the Native Wallet flow and the order has no redirect URL. Contact Banxa to configure the flow, and send `redirectUrl` when creating sell orders.
Checkout shows error `100003` ("Unable to proceed. Please try again with different payment method.")	The payment method was declined on risk grounds. Ask the customer to try a different payment method.

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.