> For a complete page index, fetch https://docs.transak.com/llms.txt

# Error Codes

Every error from the Whitelabel API returns the same JSON shape. Use `errorCode` to decide what to do next: it is stable, while the `message` wording can change.

## Error response format

**`Error response`**

```json title="Error response"
{
  "error": {
    "statusCode": 400,
    "message": "Invalid wallet address. Please provide a valid wallet address to proceed.",
    "errorCode": 4001
  }
}
```

| Field                     | Type   | Description                                                                  |
| ------------------------- | ------ | ---------------------------------------------------------------------------- |
| `error.statusCode`        | number | The HTTP status code of the response.                                        |
| `error.message`           | string | A readable description. Don't match on this text: it can change.             |
| `error.errorCode`         | number | Transak's error code. Branch your logic on this value.                       |
| `error.additionalMessage` | string | Optional. Extra detail passed on from the service that rejected the request. |

## How to handle errors

* **Branch on `errorCode`, not on the HTTP status.** Some errors are passed on from the Transak service that rejected the request, so the same `errorCode` can come with a different HTTP status on different endpoints. For example, `4001` (invalid wallet address) returns `400` on [Bank Transfer: Create Order](/api/whitelabel/payments/bank-transfer/create-order) and `422` on the headless payment endpoints.
* **`401` errors mostly return `1002`** (the KYC Reliance endpoints return `1010`). The user or partner token is missing, invalid or expired. Refresh the token or log the user in again.
* **Request validation errors return `400` with `9001`.** The `message` names the field, for example `quoteId is required`.
* **Unrecognised errors fall back to a default code**: `9999` in most cases, `4099` for order errors and `6099` for headless payment errors. Retry once, then contact Transak support with the request details.
* **Rate limit.** The API gateway allows 40 requests per IP address every 10 seconds. See [What is the API Rate Limit?](/guides/partner-faqs#what-is-the-api-rate-limit) to request a higher limit.

## Authentication errors (10xx)

| errorCode | Message                                                                                               | What to do                                                                                                                                     |
| --------- | ----------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| `1001`    | Your verification code is invalid. Please go back and generate a new one.                             | The OTP is wrong. Ask the user to request a new code with [Send User OTP](/api/whitelabel/user/send-user-otp).                                 |
| `1002`    | Invalid or missing authentication token.                                                              | Send a valid `authorization` (Transak Auth) or `x-access-token` (Partner Auth) header. Refresh or log in again if the token expired.           |
| `1003`    | Your verification code is expired. Please go back and generate a new one.                             | Request a new OTP.                                                                                                                             |
| `1004`    | Failed to send email                                                                                  | The OTP email couldn't be sent. Retry Send User OTP.                                                                                           |
| `1005`    | Failed to verify OTP                                                                                  | Retry Verify User OTP.                                                                                                                         |
| `1006`    | Failed to logout                                                                                      | Retry Logout User.                                                                                                                             |
| `1007`    | Invalid OTP                                                                                           | The OTP is wrong. Ask the user to check the code or request a new one.                                                                         |
| `1009`    | Invalid Partner API Key                                                                               | Check `x-api-key` (and `apiKey` where required) belongs to the environment you're calling.                                                     |
| `1010`    | Invalid token                                                                                         | The token is invalid. Generate a new one.                                                                                                      |
| `1011`    | Failed to refresh token                                                                               | The access token may already have expired. Log the user in again with an OTP.                                                                  |
| `1012`    | Authorization Required                                                                                | Send the `authorization` header.                                                                                                               |
| `1013`    | OTP attempts exceeded                                                                                 | Too many wrong OTPs. Ask the user to request a new code later.                                                                                 |
| `1014`    | Invalid or missing access-token.                                                                      | Send a valid Partner Access Token in `x-access-token`. See [how to create a Partner Access Token](/guides/how-to-create-partner-access-token). |
| `1015`    | Your session has expired, Please re-login and try again                                               | Log the user in again.                                                                                                                         |
| `1016`    | You have reached maximum retry attempts. Please try again after sometime                              | Wait before retrying.                                                                                                                          |
| `1019`    | You can request a new OTP after 1 minute.                                                             | Wait 60 seconds before calling Send User OTP again.                                                                                            |
| `1020`    | Your account has been locked due to multiple failed OTP attempts. You can try again after 24 hours.   | The user must wait 24 hours.                                                                                                                   |
| `1023`    | User not found. Please onboard the user first.                                                        | Partner Auth (Auth Reliance): call [Onboard User](/api/whitelabel/user/onboard-user-auth-reliance) first.                                      |
| `1024`    | Services are temporarily unavailable in your region. Please bear with us - we expect to be back soon. | The service isn't available for the user's region right now.                                                                                   |

## User and FCA errors (20xx)

| errorCode                    | Message                                                                                                      | What to do                                                                                                |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------- |
| `2001`                       | Missing required apiKey parameter                                                                            | Send the `apiKey` query parameter.                                                                        |
| `2002`–`2019`, `2023`–`2027` | FCA flow errors, for example `User is not eligible for FCA flow` or `Agreement already signed`               | UK users only. Read the `message` and follow [How to Submit FCA Requirements](/guides/how-to-submit-fca). |
| `2020`                       | This phone number is already registered                                                                      | Another Transak account uses this mobile number. Ask the user for a different number.                     |
| `2021`                       | The phone number entered is invalid. Please check the selected country and entered digits.                   | Send the mobile number in E.164 format with the right country code.                                       |
| `2022`                       | Invalid SSN. Please enter a valid Social Security Number.                                                    | Check the SSN format before calling [Submit SSN](/api/whitelabel/kyc/submit-ssn).                         |
| `2028`                       | Failed to retrieve VASPs data                                                                                | Retry Get VASPs.                                                                                          |
| `2029`                       | Invalid VASP data format                                                                                     | Check the VASP details sent with the order.                                                               |
| `2030`                       | Your account has been disabled. Please get in touch with us at [fraud@transak.com](mailto:fraud@transak.com) | Returned with `403`. Don't retry; the user must contact Transak.                                          |
| `2031`                       | Failed to get saved cards                                                                                    | Retry Get Saved Cards.                                                                                    |
| `2032`                       | Failed to delete saved card                                                                                  | Retry Delete Saved Card.                                                                                  |
| `2033`                       | This SSN is already registered                                                                               | Another Transak account uses this SSN.                                                                    |

## KYC errors (30xx)

| errorCode | Message                                                                  | What to do                                                                            |
| --------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
| `3001`    | Address details not found. Please enter your address details to proceed. | Submit the address with [Patch User Details](/api/whitelabel/kyc/patch-user-details). |
| `3002`    | You don't meet our age requirements                                      | The user is under the minimum age. Don't retry.                                       |
| `3012`    | Unable to submit KYC reliance data                                       | Check the KYC Reliance request and retry.                                             |
| `3015`    | Invalid postal codes, please enter your country postal code              | Send a postal code that matches the user's country.                                   |

## Order errors (40xx)

| errorCode | Message                                                                   | What to do                                                                                                                                                                  |
| --------- | ------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `4001`    | Invalid wallet address. Please provide a valid wallet address to proceed. | Check the address is valid for the selected cryptocurrency and network.                                                                                                     |
| `4002`    | Please complete your KYC to place an order.                               | Finish KYC: call [Get KYC Requirement](/api/whitelabel/kyc/get-kyc-requirement) and complete the pending steps.                                                             |
| `4003`    | Please upgrade your kyc to next level to proceed with this transaction    | The order needs a higher KYC level. Complete the forms from [Get Additional Requirements](/api/whitelabel/kyc/get-additional-requirements).                                 |
| `4004`    | Invalid request                                                           | Check the request parameters.                                                                                                                                               |
| `4005`    | Order exists                                                              | The user already has an active order. Use [Get Active Orders](/api/whitelabel/orders/get-active-orders), then complete or [cancel](/api/whitelabel/orders/cancel-order) it. |
| `4006`    | Unable to create order                                                    | Retry. If it keeps failing, contact support.                                                                                                                                |
| `4007`    | Unable to get order limit                                                 | Retry Get User Limits.                                                                                                                                                      |
| `4008`    | Unable to cancel order                                                    | Retry Cancel Order.                                                                                                                                                         |
| `4009`    | Unable to get order                                                       | Retry Get Order By ID.                                                                                                                                                      |
| `4010`    | Unable to payment confirmation                                            | Retry Confirm Payment.                                                                                                                                                      |
| `4011`    | Unable to get orders                                                      | Retry Get Orders.                                                                                                                                                           |
| `4012`    | Order not found                                                           | Check the `orderId`.                                                                                                                                                        |
| `4013`    | Minimum amount should be more than …                                      | The amount is below the minimum. Get a new quote for a higher amount.                                                                                                       |
| `4015`    | Invalid payment method for currency combination                           | The payment method isn't available for this fiat and crypto. Pick another payment method.                                                                                   |
| `4016`    | FCA criteria not met, Please complete the assessments.                    | UK users: complete the FCA steps first.                                                                                                                                     |
| `4021`    | Something went wrong, try again later!                                    | Retry later.                                                                                                                                                                |
| `4024`    | Quote expired!                                                            | Get a new quote and retry with the new `quoteId`.                                                                                                                           |
| `4025`    | Unable to create virtual account                                          | Retry Create Virtual Account.                                                                                                                                               |
| `4027`    | User KYC must be approved to create a virtual account                     | Returned with `403`. Finish KYC before creating the virtual account.                                                                                                        |
| `4028`    | Virtual bank account not found                                            | No virtual account yet. Call Create Virtual Account.                                                                                                                        |
| `4031`    | This endpoint accepts only the partner access token.                      | Call this endpoint with Partner Auth (`x-access-token`) only.                                                                                                               |

## Lookup and quote errors (50xx)

| errorCode | Message                                                                           | What to do                                                                                                        |
| --------- | --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `5001`    | Failed to retrieve crypto currency data                                           | Retry Get Crypto Currencies.                                                                                      |
| `5002`    | Failed to retrieve fiat currency data                                             | Retry Get Fiat Currencies.                                                                                        |
| `5003`    | Failed to retrieve countries data                                                 | Retry Get Countries.                                                                                              |
| `5004`    | Failed to retrieve quote data                                                     | Retry Get Quote.                                                                                                  |
| `5005`    | Missing required apiKey parameter                                                 | Send the `apiKey` query parameter.                                                                                |
| `5006`    | Invalid payment method                                                            | Use a payment method from [Get Fiat Currencies](/api/whitelabel/lookup/get-fiat-currencies).                      |
| `5007`    | Invalid network id                                                                | Use a network from [Get Crypto Currencies](/api/whitelabel/lookup/get-crypto-currencies).                         |
| `5008`    | Invalid fiat currency                                                             | Use a fiat currency from Get Fiat Currencies.                                                                     |
| `5009`    | Minimum buy amount requirement not met                                            | Increase the amount.                                                                                              |
| `5010`    | Order limit exceeded                                                              | The amount is above the user's limit. Lower it, or check [Get User Limits](/api/whitelabel/user/get-user-limits). |
| `5011`    | You are not allowed to buy … on …. Please change the cryptocurrency to proceed.   | The cryptocurrency isn't available in the user's KYC country. Pick another cryptocurrency or network.             |
| `5012`    | We are unable to verify your session right now. Please try again after some time. | Retry later.                                                                                                      |

## Headless payment errors (60xx)

Returned by the headless Apple Pay, Google Pay and Cards flows: [Transaction Session](/api/whitelabel/payments/headless-cards/transaction-session-api) and Create Order with a `requestId`.

| errorCode | Message                                                                                                                                                                     | What to do                                                                                                       |
| --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `6002`    | KYC is not approved. Please complete KYC before creating a session.                                                                                                         | Finish KYC, then create the session again.                                                                       |
| `6003`    | This feature is not enabled for your account. Please contact support.                                                                                                       | The payment method isn't enabled for your API key. Contact Transak.                                              |
| `6004`    | Apple Pay is not supported and is not part of this integration.                                                                                                             | Apple Pay isn't enabled for your API key.                                                                        |
| `6005`    | Quote not found or could not be loaded. / This payment method is not currently supported. Please try a different payment method. / Failed to create a session for the user. | Get a new quote, try another payment method, or retry the session.                                               |
| `6006`    | The provided wallet address is invalid for the selected cryptocurrency and network.                                                                                         | Check the wallet address for the cryptocurrency and network.                                                     |
| `6007`    | Request ID not found.                                                                                                                                                       | Check the `requestId` from the Transaction Session response.                                                     |
| `6010`    | Unable to create user account.                                                                                                                                              | Retry. If it keeps failing, contact support.                                                                     |
| `6012`    | KYC requirement is not approved for this transaction.                                                                                                                       | Returned with `422`. Complete the KYC steps from [Get KYC Requirement](/api/whitelabel/kyc/get-kyc-requirement). |
| `6014`    | Unable to process request. User location data is required for this transaction.                                                                                             | Send the user's IP address in the `x-user-ip` header.                                                            |
| `6020`    | Precondition failed. A required parameter is missing or invalid.                                                                                                            | Check the required parameters.                                                                                   |
| `6022`    | You've exceeded the maximum number of attempts. Please contact support at support.transak.com to continue.                                                                  | Contact Transak support.                                                                                         |
| `6023`    | User is already KYC verified.                                                                                                                                               | No KYC step is needed. Continue with the order.                                                                  |

## General errors (9xxx)

| errorCode | Message                                                                                                                    | What to do                                                                                          |
| --------- | -------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `9001`    | The validation message, for example `quoteId is required`                                                                  | A request validation error, or an error with no specific code. Fix the request using the `message`. |
| `9002`    | An unexpected error occurred.                                                                                              | Retry later.                                                                                        |
| `9003`    | We are unable to process your request at the moment. Please reach out to [support@transak.com](mailto:support@transak.com) | Contact Transak support.                                                                            |
| `9999`    | Varies                                                                                                                     | An error with no specific code. Retry once, then contact support with the `message`.                |