Error Codes

Error Codes

When you make a request to the iyzico API, and there are issues with the request or the payment, iyzico informs you of the error, along with the numeric code and a description of the error. The numeric code of the relevant error is returned in the errorCode variable, and the message explaining the error is in the errorMessage variable.

When an error occurs, indicated by the status parameter having a value of "failure," the iyzico payment API returns the relevant variables as follows:

• errorCode: e.g., 10051

• errorGroup: e.g., NOT_SUFFICIENT_FUNDS

• errorName: e.g., Error

• errorMessage: e.g., Insufficient card limit, insufficient balance.

Some key/value pairs may provide insufficient responses depending on the bank.

iyzico groups error codes. Bank error codes start with 10000, while Card Storage Error Messages start with 3000.

General Error Codes

General error codes are typically due to missing information in the payment details during the request. The relevant error codes and their causes are provided in the table below:

Code	Description
1	System error occurred
2	System error occurred
3	Email is mandatory
4	Email must be at most {0} characters
5	Email was sent in an incorrect format
6	Request object is mandatory
7	Date format is incorrect for {0}
8	Identity number is mandatory
9	Identity number must be at most {0} characters
10	Identity number must be at least {0} characters
11	Invalid request
12	Invalid card number
13	Invalid expiration month
14	Invalid expiration year
15	Invalid CVC
16	Cardholder name is mandatory
17	Your card’s expiration date is invalid
18	Identity number {0} was sent in an incorrect format
19	Cardholder name must be at most {0} characters
20	ConversationId must be at most {0} characters
21	Card alias must be at most {0} characters
22	IP must be at most {0} characters
23	Callback URL is mandatory
24	{0} is mandatory
25	GSM number is mandatory
26	GSM number must be at most {0} characters
27	Invalid phone number
28	Invalid metadata format
29	Claim token is mandatory
30	Member ID is mandatory
31	ConversationId may contain harmful code

Authentication Error Codes

These error messages occur when there are authentication issues while connecting to the iyzico API. The error codes and their descriptions are as follows:

Code	Description
1000	Invalid signature
1001	API details not found
1002	Merchant not found
1003	Authorization error
1004	Random string is mandatory
1005	Request object is mandatory
1006	API key is mandatory
1007	Signature is mandatory
1008	Authorization header prefix not found
1009	Authorization header string is mandatory
1010	Gateway merchant not found
1011	Authorized merchant and merchant number do not match
1012	Active platform not found
1013	User matching the application name not found
1014	Security information not found
1015	Application name is mandatory

Onboarding Error Messages

These errors occur during the onboarding process when mandatory information such as IBAN, tax office, etc., is missing. The error codes and descriptions are as follows:

Code	Description
2000	This service is only available for marketplace customers
2001	Sub-merchant not found
2002	Sub-merchant already exists
2003	subMerchantKey is mandatory
2004	subMerchantType is mandatory
2005	IBAN is mandatory
2007	subMerchantExternalId is mandatory
2008	subMerchantExternalId must be at most {0} characters
2009	Address is mandatory
2010	Address must be at most {0} characters
2011	Address must be at least {0} characters
2012	Contact name is mandatory
2013	Contact name must be at most {0} characters
2014	Contact name must be at least {0} characters
2015	Contact surname is mandatory
2016	Contact surname must be at most {0} characters
2017	Contact surname must be at least {0} characters
2018	Tax office is mandatory
2019	Tax office must be at most {0} characters
2020	Tax office must be at least {0} characters
2021	Legal company title is mandatory
2022	Legal company title must be at most {0} characters
2023	Legal company title must be at least {0} characters
2024	Tax number is mandatory
2025	Tax number must be at most {0} characters
2026	Tax number must be at least {0} characters
2027	Tax office {0} must consist of alphabetic characters
2028	Name must be at most {0} characters
2029	GSM number must be at most {0} characters
2030	The sent IBAN is in an invalid format
2031	Contact name must consist of {0} alphabetic characters
2032	Contact surname must consist of {0} alphabetic characters
2033	Legal company title must consist of {0} alphanumeric characters
2034	GSM number must not contain alphabetic characters
2035	Tax number must consist of numeric characters
2036	Swift code is mandatory
2037	Sub-merchant bank account currency must match the local bank account currency
2038	IBANs for Turkish lira accounts must start with TR
2039	Swift code must be at most {0} characters
2040	Invalid transfer description

Card Storage Validation Errors

These errors occur when mandatory information for card storage requests is missing. The relevant error codes and descriptions are as follows:

Code	Description
3000	externalId must be at most {0} characters
3001	cardUserKey is mandatory
3002	cardToken is mandatory
3003	Card information is mandatory
1401	Card number is mandatory
3014	merchantId information is mandatory
3015	changeManagementId information is mandatory
3016	anonymizationType information is mandatory
3022	toMerchantId information is mandatory
3004	An error occurred during card storage
3005	cardUserKey not found
3006	cardToken not found
3007	Card storage feature is not defined
3008	Encryption error
3009	Decryption error
3010	Card not found
3011	Card user key did not match
3012	Email cannot contain card number
3013	externalId cannot contain card number
3017	An error occurred during card anonymization
3018	Card storage blacklist feature is not defined
3019	No active blacklist found
3020	An active blacklist already exists
3021	An error occurred during card user update

Marketplace Payout Errors

These errors occur during marketplace payouts. The relevant error codes and descriptions are as follows:

Code	Description
4000	subMerchantKey is mandatory
4001	Reason is mandatory
4002	Sub-merchant not found
4003	No balance record for the sender
4004	Insufficient balance for the sender
4005	Merchant is not authorized to use the settlement service
4006	To perform a settlement, the sub-merchant's setting for sending funds to balance must be disabled