Errors and validations

Error reference

Errors come in three layers:

1. HTTP status: 400 for validation / business errors, 5xx for infrastructure issues.
2. Response envelope: top-level error_code + error_message.
3. errors[] array: granular per-field failures. For Checkout validation errors, every entry uses error_code 100000; the message identifies the field and rule that failed.

Error envelope

{
  "error_code": 0,
  "error_message": "Request data is invalid.",
  "errors": [
    { "error_code": 100000, "error_message": "order_amount: This value should not be blank." },
    { "error_code": 100000, "error_message": "order_currency: This value is not valid." }
  ]
}

Validation errors (1xxxxx)

Payment / Order (100000)

All Payment / Order errors return the code 100000. The difference between each case is the error message.

Code	Error Message	Category	Cause	Fix
100000	payer_card_exp_month: This value should not be blank.	Missing field	Card expiry month not provided.	Send payer_card_exp_month (1–12).
100000	payer_card_exp_year: This value should not be blank.	Missing field	Card expiry year not provided.	Send payer_card_exp_year (4-digit year).
100000	payer_card_cvv: This value should not be blank.	Missing field	CVV code missing.	Include payer_card_cvv in the payload.
100000	order_id: This value should not be blank.	Missing field	Order identifier not sent.	Pass a unique order_id with each request.
100000	order_amount: This value should not be blank.	Missing field	Payment amount missing.	Include order_amount in the request.
100000	order_amount: This value should be greater than 0.	Invalid value	Amount is zero or negative.	Ensure order_amount > 0.
100000	order_currency: This value should not be blank.	Missing field	Currency code not sent.	Send a valid 3-letter ISO currency code.
100000	order_description: This value should not be blank.	Missing field	Order description is empty.	Provide a non-blank order_description.
100000	payee_card_number: This value should not be blank.	Missing field	Payee card number missing (payout).	Include payee_card_number for payout requests.
100000	term_url_3ds: This value should not be blank.	Missing field	3DS return URL not provided.	Set term_url_3ds to the cardholder redirect URL after 3DS.
100000	amount: Amount is not valid.	Invalid value	Amount format is incorrect.	Send amount as a numeric value with up to 2 decimal places.
100000	card_exp_year: The date is expired and not valid.	Expired card	Card expiry year is in the past.	Use a valid, non-expired card.
100000	The expiration date of card is expired and not valid.	Expired card	Card expiry date is in the past.	Verify card expiry before sending the request.
100000	Request from this ip is not allowed.	IP restriction	Requesting IP is not whitelisted for the merchant.	Whitelist the IP in admin settings or send from an allowed IP.
100000	order_id: Duplicate payment.	Duplicate request	A payment with the same order_id already exists.	Use a unique order_id for every new payment attempt.
100000	merchant_key: Wrong merchant operation.	Auth / config	Merchant key is not permitted for this operation type.	Check that you are using the correct merchant key.
100000	schedule_id: Schedule is paused	Schedule state	The referenced schedule is currently paused.	Resume the schedule before sending recurring transactions.
100000	Schedule is not found	Schedule state	schedule_id does not exist.	Verify the schedule_id; create the schedule if deleted.
100000	schedule_id: Schedule cannot be used for non-recurring transaction	Schedule state	schedule_id passed for a one-time payment.	Remove schedule_id for non-recurring requests.
100000	Void is not allowed	Operation restriction	Void is disabled for this merchant or payment.	Enable void in MID settings or contact support.
100000	Refund is not allowed	Operation restriction	Refund is disabled for this merchant or payment.	Enable refund in MID settings or contact support.

Payment processing errors (2xxxxx)

Currency (203xxx)

Error Code	Error Message	Category	Possible Reason	Fix
203001	Invalid commission settings: total amount less than zero.	Currency Rates	Commission rules produce a negative total — misconfigured fee settings.	Review fee settings in admin; ensure fees do not exceed the transaction amount.
203002	Base Currency not found in ECB XML.	Currency Rates	ECB rate feed lacks the configured base currency.	Use a supported ECB base currency (e.g., EUR) or switch rate provider.
203003	Base Currency not found in Bank-Ua XML.	Currency Rates	Ukrainian bank rate feed missing the base currency.	Verify the base currency is available in the Bank-Ua feed.
203004	Currency rate not found.	Currency Rates	Exchange rate for the currency pair is unavailable.	Check the currency pair is supported; update rate feed configuration.
203005	Currency not found.	Currency Rates	Currency code does not exist in the system.	Use a valid ISO 4217 currency code.
203006	Base Currency not found in CurrencyScoop service.	Currency Rates	CurrencyScoop feed lacks the base currency.	Verify CurrencyScoop config or change the base currency.

Balancer / routing (204xxx, 240001)

Error Code	Error Message	Category	Possible Reason	Fix
240001	Not available action. Check MID configuration.	Traffic Balancer	Requested action is not enabled for the assigned MID.	Enable the action in MID configuration.
204001	Merchant mapping not found for current channel.	Traffic Balancer	No merchant-to-channel mapping exists for this transaction.	Create a merchant mapping for the relevant channel in admin.
204002	Enabled merchant mappings or MIDs not found.	Traffic Balancer	No active mappings/MIDs match transaction parameters.	Ensure at least one active merchant mapping/MID is configured.
204003	Payment type not supported.	Traffic Balancer	Payment type (e.g., recurring) not enabled for the MID.	Enable the required payment type in MID settings.
204004	Payment method not supported.	Traffic Balancer	Payment method not supported by the MID.	Add the required method to the MID configuration.
204005	Payment action not supported.	Traffic Balancer	Action (capture, refund, etc.) is not enabled.	Enable the action in MID settings.
204006	Payment system/brand not supported.	Traffic Balancer	Card scheme (Visa, MC, etc.) not accepted by this MID.	Configure the card brand in MID settings or route to a different MID.
204007	Day MID limit is not set or exceeded.	Traffic Balancer	Daily limit is missing or has been reached.	Set or increase the daily MID limit; or wait until the next day.
204008	Merchant mapping limit is not set or exceeded.	Traffic Balancer	Merchant mapping limit missing or exceeded.	Update the merchant mapping limit configuration.
204009	Payment type not found.	Traffic Balancer	Payment type ID does not exist.	Use a valid, configured payment type.
204010	Payment method not found.	Traffic Balancer	Payment method ID does not exist.	Use a valid payment method; check configuration.
204011	Payment system/brand not found.	Traffic Balancer	Card scheme identifier not recognised.	Verify the payment system/brand value in the request.
204012	Payment currency not found.	Traffic Balancer	Currency not configured for this merchant/MID.	Add the currency to MID config or use a supported currency.
204013	Payment action not found.	Traffic Balancer	Requested action code does not exist.	Use a valid action code.
204014	Month MID limit is exceeded.	Traffic Balancer	Monthly processing limit reached.	Request a limit increase from the acquirer or wait for the new month.
204015	Week Merchant mapping limit is exceeded.	Traffic Balancer	Weekly mapping limit reached.	Increase the weekly limit or wait for the new week.
204016	Payment currency not supported.	Traffic Balancer	Currency not enabled for this MID.	Enable the currency in MID settings or use a supported currency.
204017	Payment amount after exchange equals 0.	Traffic Balancer	Currency conversion results in zero (very small amount).	Increase the transaction amount or review conversion settings.
205001	Merchant mappings not found.	Payment Builders	No merchant mapping exists for the given parameters.	Create the required merchant mapping in admin.
205002	Recurring is not supported by specified initial payment.	Payment Builders	Initial payment does not have recurring enabled.	Make the initial payment with recurring=true and ensure it is in a valid state.
205003	Merchant not found.	Payment Builders	merchant_key does not correspond to an existing merchant.	Verify the merchant_key in your request credentials.
205004	Payment not found.	Payment Builders	Referenced payment ID does not exist.	Check the payment ID; confirm it was created successfully.
205005	Card token is invalid or not found.	Payment Builders	Token does not exist or is malformed.	Re-tokenize the card or verify the token value.
205006	Card token is expired.	Payment Builders	Card token has passed its expiry.	Generate a new card token.
205007	Card token is not accessible.	Payment Builders	Merchant is not authorised to use this token.	Use a token belonging to this merchant, or re-tokenize.
205008	This order is scheduled already.	Payment Builders	A schedule already exists for this order_id.	Use a different order_id or manage the existing schedule.

Payment flow (208xxx): post-payment operations

Error Code	Error Message	Category	Possible Reason	Fix
208002	Not acceptable to request the 3DS for payment not in 3DS status.	Payment Flow	3DS requested for a payment not awaiting 3DS.	Only trigger 3DS for payments in 3DS-pending status.
208003	Not acceptable to request the capture for payment not in pending status.	Payment Flow	Capture attempted on a non-pending payment.	Ensure the payment is authorised (pending) before capturing.
208004	Not acceptable to request the capture for amount bigger than auth amount.	Payment Flow	Capture amount exceeds authorised amount.	Capture only up to the authorised amount.
208005	Not acceptable to request the refund for payment not in settled or pending status.	Payment Flow	Refund on an unsettled payment.	Wait for payment to reach 'settled' status before refunding.
208006	Not acceptable to request the refund for amount bigger than payment amount.	Payment Flow	Refund amount exceeds original payment.	Refund only up to the original payment amount.
208007	Not acceptable to request the reversal for payment not in pending status.	Payment Flow	Reversal on a non-pending payment.	Reverse only pending/authorised payments.
208008	Not acceptable to request the reversal for amount bigger than payment amount.	Payment Flow	Reversal amount exceeds payment amount.	Reversal must not exceed the original amount.
208009	Not acceptable to request the reversal for partial amount.	Payment Flow	Partial reversal not supported.	Reverse the full amount or use a refund for partial amounts.
208010	Not acceptable to request the chargeback for amount bigger than payment's amount.	Payment Flow	Chargeback amount exceeds original payment.	Chargeback amount must be equal or lesser than the original payment amount.
208011	Not acceptable to request the chargeback for date less than payment's create date.	Payment Flow	Chargeback date is before payment creation date.	Verify the chargeback date is after the payment date.
208012	Not acceptable to request the refund for partial amount.	Payment Flow	Partial refund not enabled for this merchant.	Contact support to enable partial refunds, or refund the full amount.
208013	Not acceptable to request the check for payment not in prepare status.	Payment Flow	Check requested on a non-prepare payment.	Only check payments in 'prepare' status.
208014	Not acceptable to request the void for payment not in settled status.	Payment Flow	Void on an unsettled payment.	Only void settled payments; use reversal for pending ones.
208015	Not acceptable to request the void for payment with already partial refunds.	Payment Flow	Void blocked by existing partial refunds.	Cannot void a payment that has been partially refunded.
209001	Affected payment not found.	Payment Flow	Referenced original payment does not exist.	Verify the payment ID used in the operation.
209002	Affected transaction not found.	Payment Flow	Referenced transaction ID does not exist.	Check the transaction ID and confirm it was created.
210001	Payment already in process.	Payment Flow	Concurrent request for the same payment is running.	Wait for the first request to complete before retrying.
210002	Refund via API is not supported. Only from the connector admin portal.	Payment Flow	Connector does not support API-based refunds.	Issue refunds through the connector admin portal.

Miscelaneous

Error Code	Error Message	Category	Possible Reason	Fix
220002	Use merchant test key.	Test Transactions	Live merchant key used in sandbox environment.	Use the merchant test key for sandbox transactions.
230001	Invalid commission settings: total amount less than zero.	Payment Commission	Commission config produces a negative total.	Fix commission settings so fees do not exceed the transaction amount.

Hash validation

Checkout always validates the request hash. An invalid hash is rejected with:

{
  "error_code": 0,
  "error_message": "Request data is invalid.",
  "errors": [
    { "error_code": 100000, "error_message": "hash: Hash is not valid." }
  ]
}

Common causes: wrong field order or count; missing uppercase(); using merchant key instead of password; using production password against sandbox URL; trailing whitespace in the password; using the wrong hash formula for the operation (each operation has its own field list; see Hash signature).

Example: validation failure

Request

curl -X POST "$CHECKOUT_URL/api/v1/session" \
  -H "Content-Type: application/json" \
  -d '{
    "merchant_key": "27106696-...",
    "operation": "credit",
    "methods": [""],
    "order": { "number": "", "amount": "1.2", "currency": "Dollar", "description": "" },
    "cancel_url": "1.com",
    "success_url": "",
    "hash": "728d13b95cf2b6b3ee04b20dc2fc9889ffff1cf4"
  }'

Response: 400 Bad Request

{
  "error_code": 0,
  "error_message": "Request data is invalid.",
  "errors": [
    { "error_code": 100000, "error_message": "order_number: This value should not be blank." },
    { "error_code": 100000, "error_message": "order_amount: This value should not be blank." },
    { "error_code": 100000, "error_message": "order_currency: This value is not valid." }
  ]
}

---