Common error responses from the Banxa Hosted Checkout API, what they mean, and how to resolve them.
| 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. |
| 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. |
| 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. |
| 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. |
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.