Skip to navigation

Error Codes

Error response format and errorCode reference for the Transak Whitelabel API.
View as Markdown

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
{
"error": {
"statusCode": 400,
"message": "Invalid wallet address. Please provide a valid wallet address to proceed.",
"errorCode": 4001
}
}
FieldTypeDescription
error.statusCodenumberThe HTTP status code of the response.
error.messagestringA readable description. Don’t match on this text: it can change.
error.errorCodenumberTransak’s error code. Branch your logic on this value.
error.additionalMessagestringOptional. 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 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? to request a higher limit.

Authentication errors (10xx)

errorCodeMessageWhat to do
1001Your 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.
1002Invalid 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.
1003Your verification code is expired. Please go back and generate a new one.Request a new OTP.
1004Failed to send emailThe OTP email couldn’t be sent. Retry Send User OTP.
1005Failed to verify OTPRetry Verify User OTP.
1006Failed to logoutRetry Logout User.
1007Invalid OTPThe OTP is wrong. Ask the user to check the code or request a new one.
1009Invalid Partner API KeyCheck x-api-key (and apiKey where required) belongs to the environment you’re calling.
1010Invalid tokenThe token is invalid. Generate a new one.
1011Failed to refresh tokenThe access token may already have expired. Log the user in again with an OTP.
1012Authorization RequiredSend the authorization header.
1013OTP attempts exceededToo many wrong OTPs. Ask the user to request a new code later.
1014Invalid or missing access-token.Send a valid Partner Access Token in x-access-token. See how to create a Partner Access Token.
1015Your session has expired, Please re-login and try againLog the user in again.
1016You have reached maximum retry attempts. Please try again after sometimeWait before retrying.
1019You can request a new OTP after 1 minute.Wait 60 seconds before calling Send User OTP again.
1020Your account has been locked due to multiple failed OTP attempts. You can try again after 24 hours.The user must wait 24 hours.
1023User not found. Please onboard the user first.Partner Auth (Auth Reliance): call Onboard User first.
1024Services 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)

errorCodeMessageWhat to do
2001Missing required apiKey parameterSend the apiKey query parameter.
2002–2019, 2023–2027FCA flow errors, for example User is not eligible for FCA flow or Agreement already signedUK users only. Read the message and follow How to Submit FCA Requirements.
2020This phone number is already registeredAnother Transak account uses this mobile number. Ask the user for a different number.
2021The 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.
2022Invalid SSN. Please enter a valid Social Security Number.Check the SSN format before calling Submit SSN.
2028Failed to retrieve VASPs dataRetry Get VASPs.
2029Invalid VASP data formatCheck the VASP details sent with the order.
2030Your account has been disabled. Please get in touch with us at fraud@transak.comReturned with 403. Don’t retry; the user must contact Transak.
2031Failed to get saved cardsRetry Get Saved Cards.
2032Failed to delete saved cardRetry Delete Saved Card.
2033This SSN is already registeredAnother Transak account uses this SSN.

KYC errors (30xx)

errorCodeMessageWhat to do
3001Address details not found. Please enter your address details to proceed.Submit the address with Patch User Details.
3002You don’t meet our age requirementsThe user is under the minimum age. Don’t retry.
3012Unable to submit KYC reliance dataCheck the KYC Reliance request and retry.
3015Invalid postal codes, please enter your country postal codeSend a postal code that matches the user’s country.

Order errors (40xx)

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

Lookup and quote errors (50xx)

errorCodeMessageWhat to do
5001Failed to retrieve crypto currency dataRetry Get Crypto Currencies.
5002Failed to retrieve fiat currency dataRetry Get Fiat Currencies.
5003Failed to retrieve countries dataRetry Get Countries.
5004Failed to retrieve quote dataRetry Get Quote.
5005Missing required apiKey parameterSend the apiKey query parameter.
5006Invalid payment methodUse a payment method from Get Fiat Currencies.
5007Invalid network idUse a network from Get Crypto Currencies.
5008Invalid fiat currencyUse a fiat currency from Get Fiat Currencies.
5009Minimum buy amount requirement not metIncrease the amount.
5010Order limit exceededThe amount is above the user’s limit. Lower it, or check Get User Limits.
5011You 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.
5012We 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 and Create Order with a requestId.

errorCodeMessageWhat to do
6002KYC is not approved. Please complete KYC before creating a session.Finish KYC, then create the session again.
6003This feature is not enabled for your account. Please contact support.The payment method isn’t enabled for your API key. Contact Transak.
6004Apple Pay is not supported and is not part of this integration.Apple Pay isn’t enabled for your API key.
6005Quote 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.
6006The provided wallet address is invalid for the selected cryptocurrency and network.Check the wallet address for the cryptocurrency and network.
6007Request ID not found.Check the requestId from the Transaction Session response.
6010Unable to create user account.Retry. If it keeps failing, contact support.
6012KYC requirement is not approved for this transaction.Returned with 422. Complete the KYC steps from Get KYC Requirement.
6014Unable to process request. User location data is required for this transaction.Send the user’s IP address in the x-user-ip header.
6020Precondition failed. A required parameter is missing or invalid.Check the required parameters.
6022You’ve exceeded the maximum number of attempts. Please contact support at support.transak.com to continue.Contact Transak support.
6023User is already KYC verified.No KYC step is needed. Continue with the order.

General errors (9xxx)

errorCodeMessageWhat to do
9001The validation message, for example quoteId is requiredA request validation error, or an error with no specific code. Fix the request using the message.
9002An unexpected error occurred.Retry later.
9003We are unable to process your request at the moment. Please reach out to support@transak.comContact Transak support.
9999VariesAn error with no specific code. Retry once, then contact support with the message.