# Error Codes

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. |
| `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. |


## 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](/products/hosted-checkout/docs/getting-started/authentication-and-environments). |
| Webhook signature verification failing | Verify with your HMAC secret, not the v2 `x-api-key`. See [Webhooks](/products/hosted-checkout/docs/transaction-lifecycle/webhooks#securing-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. |


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.