Error codes

On failure the envelope carries success: false, data: null, and a pair of codes: semanticCode (a string, and the one to branch on) and errorCode (a number, kept for older integrations).

Branch on semanticCode. The HTTP status tells you nothing in v2.

Errors any signed endpoint can return

Signature verification runs before any business logic, so every signed endpoint can return all of these.

errorCode	semanticCode	When
1	INTERNAL_SERVER_ERROR	Server error. Also what you get if your key material is structurally unusable.
2	INVALID_SIGNATURE	The signature does not match the canonical string, or your public key is missing.
3	PARTNER_ACCOUNT_LOCKED	Your partner account is not active.
4	PARTNER_NOT_FOUND	Unknown partnerCode.
5	INVALID_REQUEST_DATA	Request validation failed.
19	PARTNER_IP_NOT_ALLOWED	The calling IP is not on your allowlist.

The user and their KYC

errorCode	semanticCode	When
26	USER_REGISTRATION_REQUIRED	The end user could not be provisioned.
27	USER_EMAIL_INVALID	userEmail is malformed.
34	USER_KYC_VERIFICATION_REQUIRED	The user has no KYC profile, or it is not VERIFIED. Not-submitted, in-progress and rejected all collapse into this one code.
35	USER_KYC_UNDER_PROCESSING	A KYC submission is already in flight — resubmission is blocked.
50	REQUESTED_INFO_NOT_FOUND	No user or KYC profile exists for that email under your partner account.
52	KYC_DOCUMENT_ALREADY_REGISTERED	KYC is already verified, or that nationalId belongs to another of your users.
58	KYC_DOCUMENT_FORMAT_INVALID	A document is not a valid base64 data URL.
59	NATIONALITY_NOT_SUPPORTED	The user's nationality is missing, or blocked for this service and currency.
60	HIGHER_KYC_LEVEL_REQUIRED	The provider needs a higher KYC level than the profile carries.
61	KYC_PROFILE_UNDER_REVIEW	The provider-side KYC profile is still pending.
62	KYC_PROFILE_NOT_ELIGIBLE	The provider-side KYC profile was rejected.
63	BANK_ACCOUNT_KYC_MISMATCH	The payout account must match the user's KYC identity.
64	HIGH_RISK_USER	The user's email is blacklisted.

The recipient and the payout

errorCode	semanticCode	When
17	INVALID_TRANSFER_CONTENT	The transfer content has accents or special characters.
18	INVALID_BANK_ACCOUNT	The bank account could not be verified.
33	QR_CODE_NOT_SUPPORTED	The QR format is not supported.
44	INVALID_PAYMENT_INFO	A PHP payout is missing recipientName.
48	PAYMENT_CHANNEL_NOT_SUPPORTED	No payment channel for this fiat currency.
53	FIAT_CURRENCY_NOT_SUPPORTED	The fiat currency is not supported by this endpoint.
56	BANK_NOT_SUPPORTED	The bank code is not in the provider's list. Fetch the current list.
65	HIGH_RISK_BANK_ACCOUNT	The recipient account or name is blacklisted.
67	QR_CODE_UNREADABLE	The QR code could not be read. It carries no message — see below.

Amounts, limits, and your fund

errorCode	semanticCode	When
7	PARTNER_INSUFFICIENT_BALANCE	Your crypto fund cannot cover the order.
16	AMOUNT_OUT_OF_RANGE	The amount is below the payment provider's own floor.
24	SELL_AMOUNT_BELOW_MIN	Below the minimum. The message carries the live limit.
25	SELL_AMOUNT_ABOVE_MAX	Above the maximum. The message carries the live limit.
36	TRANSACTION_AMOUNT_LIMIT_EXCEEDED	Per-transaction cap exceeded (in USD).
37	DAILY_AMOUNT_LIMIT_EXCEEDED	Daily amount or transaction-count cap exceeded.
42	MONTHLY_AMOUNT_LIMIT_EXCEEDED	Monthly cap exceeded.

The limits are not constants — they depend on the currency and the payment provider you route to. Read minSell / maxSell from POST /api/v2/orders/prices rather than hard-coding them.

Orders

errorCode	semanticCode	When
11	DUPLICATE_TRANSACTION_ID	externalOrderId already exists for your account.
12	TRANSACTION_CREATE_FAILED	The payout failed after the order was created. You have already been refunded, and the order detail comes back in data.
13	WEBHOOK_SECRET_NOT_FOUND	webhookSecretKey matches no registered endpoint. The order is not created.
15	TRANSACTION_NOT_FOUND	No order with that externalOrderId under your account.

DUPLICATE_TRANSACTION_ID usually means your retry succeeded the first time. Fetch the order with POST /api/v2/orders/details instead of treating it as a failure.

Service availability

These are the ones worth retrying with backoff.

errorCode	semanticCode	When
9	SERVICE_UNDER_MAINTENANCE	Fee configuration is missing for this partner, channel and currency.
20	SERVICE_TEMPORARILY_UNAVAILABLE	Under maintenance.
46	SERVICE_NOT_AVAILABLE	The service is off for your account, or no provider could be routed for this currency.
66	SERVICE_NOT_ACTIVATED	The service is not activated. Has no message — see below.

Two traps in the code table

Unmapped codes

These numeric codes are not in the mapping table, so they all arrive as semanticCode: "INTERNAL_SERVER_ERROR" while keeping their own distinct errorCode and message:

errorCode	message
21	The blockchain network requires a memo
28	The service is in maintenance. Please contact us for more details
32	The QR code is invalid. Please check and try again
39	The amount is invalid
40	This card type is no longer supported.
41	Not available in your country
43	Exceeding the daily limit
45	The amount received must be greater than {{minimum}}
47	Access denied. Please contact us for more details
49	Information already exists in the system
51	This email address has been bound to the registered account
54	The card is not activated yet, please try again later.
55	The cardholder information is being reviewed. Please try again later.
57	The amount to be converted must be greater than {{fiatAmount}}

So a semanticCode of INTERNAL_SERVER_ERROR does not always mean a server fault. If you need to distinguish these — "not available in your country" is a very different thing from a crash — you must read errorCode.

Two codes have no message

errorCode 66 and 67 are in the mapping table but not in the message table, so message comes back as the literal string "msg.66" / "msg.67". Do not show message to an end user without a fallback.

Every code

The complete table, for looking up a number you were not expecting. Messages marked with {{…}} have the live value interpolated in.

errorCode	semanticCode	message
0	SUCCESS	Your request has been successful
1	INTERNAL_SERVER_ERROR	The request could not be processed at this time. Please try again later.
2	INVALID_SIGNATURE	Invalid signature
3	PARTNER_ACCOUNT_LOCKED	Your account is locked. Please contact us for assistance
4	PARTNER_NOT_FOUND	Partner code information does not exist
5	INVALID_REQUEST_DATA	Your data is invalid. Please check and try again
6	TOKEN_NOT_SUPPORTED_ON_NETWORK	Token does not supported on this network yet.
7	PARTNER_INSUFFICIENT_BALANCE	Insufficient balance
8	NETWORK_FEE_UNAVAILABLE	Network fee not found.
9	SERVICE_UNDER_MAINTENANCE	The service is in maintenance. Please contact us for more details
10	INVALID_WALLET_ADDRESS	The wallet address is invalid. Please check and try again
11	DUPLICATE_TRANSACTION_ID	The transaction id already exists.
12	TRANSACTION_CREATE_FAILED	The transaction has not created successfully. Please try again later
13	WEBHOOK_SECRET_NOT_FOUND	The webhook secret key does not exist
14	UNKNOWN_SERVICE_TYPE	The service type is unidentified
15	TRANSACTION_NOT_FOUND	Transaction information does not exist
16	AMOUNT_OUT_OF_RANGE	The amount must be greater than 10,000 and less than 14,000,000
17	INVALID_TRANSFER_CONTENT	The transfer content must be in unaccented letters and not contain special characters
18	INVALID_BANK_ACCOUNT	The bank account information is incorrect
19	PARTNER_IP_NOT_ALLOWED	IP address not allowed
20	SERVICE_TEMPORARILY_UNAVAILABLE	The service is under maintenance. Please try again later
21	(none — arrives as INTERNAL_SERVER_ERROR)	The blockchain network requires a memo
22	BUY_AMOUNT_BELOW_MIN	You should buy an amount is greater than {{minBuy}}
23	BUY_AMOUNT_ABOVE_MAX	You should buy an amount is less than {{maxBuy}}
24	SELL_AMOUNT_BELOW_MIN	You should sell an amount is greater than {{minSell}}
25	SELL_AMOUNT_ABOVE_MAX	You should sell an amount is less than {{maxSell}}
26	USER_REGISTRATION_REQUIRED	You have to register an account on our platform for continue using the service
27	USER_EMAIL_INVALID	The registration email is invalid.
28	(none)	The service is in maintenance. Please contact us for more details
29	EMAIL_CONFIRMATION_CODE_INCORRECT	The confirmation code is incorrect. Please try again
30	EMAIL_CONFIRMATION_CODE_EXPIRED	The confirmation code has expired. Please try again
31	VERIFICATION_EMAIL_LIMIT_REACHED	You are reach to daily limit. Please try again later
32	(none)	The QR code is invalid. Please check and try again
33	QR_CODE_NOT_SUPPORTED	The QR code has not support yet.
34	USER_KYC_VERIFICATION_REQUIRED	You must verify your account on our platform to continue using the service.
35	USER_KYC_UNDER_PROCESSING	Your information is being processed.
36	TRANSACTION_AMOUNT_LIMIT_EXCEEDED	You should make transactions with a total payment amount less than {{fiatAmount}} USD
37	DAILY_AMOUNT_LIMIT_EXCEEDED	The total transaction amount in a day must not exceed {{fiatAmount}} USD
38	LOGIN_SESSION_EXPIRED	The login session has expired — the only code that changes the HTTP status (to 401).
39	(none)	The amount is invalid
40	(none)	This card type is no longer supported.
41	(none)	Not available in your country
42	MONTHLY_AMOUNT_LIMIT_EXCEEDED	Exceeding the monthly deposit limit
43	(none)	Exceeding the daily limit
44	INVALID_PAYMENT_INFO	Invalid payment information
45	(none)	The amount received must be greater than {{minimum}}
46	SERVICE_NOT_AVAILABLE	The service is not available yet. Please contact us for support.
47	(none)	Access denied. Please contact us for more details
48	PAYMENT_CHANNEL_NOT_SUPPORTED	This channel is invalid or currently not available for use.
49	(none)	Information already exists in the system
50	REQUESTED_INFO_NOT_FOUND	The information does not exist in the system yet, please try again later.
51	(none)	This email address has been bound to the registered account
52	KYC_DOCUMENT_ALREADY_REGISTERED	This document number has already been registered. Please do not resubmit.
53	FIAT_CURRENCY_NOT_SUPPORTED	This function is not yet supported on this fiat currency.
54	(none)	The card is not activated yet, please try again later.
55	(none)	The cardholder information is being reviewed. Please try again later.
56	BANK_NOT_SUPPORTED	The bank is not supported yet.
57	(none)	The amount to be converted must be greater than {{fiatAmount}}
58	KYC_DOCUMENT_FORMAT_INVALID	The submitted document is invalid, please check again.
59	NATIONALITY_NOT_SUPPORTED	This service is not available for your current nationality.
60	HIGHER_KYC_LEVEL_REQUIRED	You need to verify your profile at a higher level to continue using the service.
61	KYC_PROFILE_UNDER_REVIEW	Your profile is currently under review for this payment service.
62	KYC_PROFILE_NOT_ELIGIBLE	Your profile is currently not eligible to use this payment service.
63	BANK_ACCOUNT_KYC_MISMATCH	The service only allows payments to the bank account that matches the KYC information.
64	HIGH_RISK_USER	Cant operate high risk user. Please contact us for support.
65	HIGH_RISK_BANK_ACCOUNT	Unable to process due to a high-risk bank account. Please contact us for support.
66	SERVICE_NOT_ACTIVATED	(none — you receive the literal string msg.66)
67	QR_CODE_UNREADABLE	(none — you receive the literal string msg.67)