API error reference

Complete list of error codes returned by the payment gateway. Use Cmd/Ctrl-F to jump to a code or message. New entries are added as part of each release; see the changelog for the version they appeared in.

Where each code can show up

• Synchronous responses to API requests carry error_code and error_message fields, with HTTP 400.
• Callbacks carry the same fields on failed payments.
• Not-found responses since 6.7.0 follow a per-entity rule rather than a per-operation one. Operations whose underlying entity is a transaction or order (GET_TRANS_STATUS, GET_TRANS_STATUS_BY_ORDER, S2S CARD CAPTURE) return 101000 with a specific message. Operations against payment, schedule, or recurring entities (VOID, CREDITVOID, DELETE_SCHEDULE, UPDATE_SCHEDULE, RECURRING_SALE) continue to return 100000, also with specific messages. The per-action mapping lives in the changelog of the changelog and the table below.

---

Validation errors

These are returned synchronously when the request payload fails schema or business-rule validation. HTTP 400.

100000 and 101000: General validation

Error code	Error message	Sub-type	Possible reason	How to fix
100000	card_number: This value should not be blank.	Missing field	card_number not in the request payload.	Add card_number to the request.
100000	payer_card_exp_month: This value should not be blank.	Missing field	Expiry month not provided.	Send payer_card_exp_month (1-12).
100000	payer_card_exp_year: This value should not be blank.	Missing field	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 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	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 4217 code.
100000	order_description: This value should not be blank.	Missing field	Description 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 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	Expiry year in the past.	Use a valid, non-expired card.
100000	The expiration date of card is expired and not valid.	Expired card	Expiry date in the past.	Verify card expiry before sending the request.
100000	Request from this ip is not allowed.	IP restriction	Requesting IP not whitelisted.	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 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 paused.	Resume the schedule before sending recurring transactions.
100000	Schedule not found	Not found (schedule entity)	S2S CARD DELETE_SCHEDULE or UPDATE_SCHEDULE against an unknown schedule_id. The wording is Schedule not found (no is) as returned by the API.	Verify the schedule_id matches an existing schedule that has not already been 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	Payment not found.	Not found (payment entity)	S2S CARD VOID or CREDITVOID against an unknown trans_id. Returned with HTTP 400.	Verify the trans_id matches an existing payment in a state that allows void / credit-void.
100000	Incorrect transaction	Not found (recurring init pair)	S2S CARD RECURRING_SALE whose recurring_first_trans_id + recurring_token pair does not match a valid recurring initial transaction. Surfaces only after schema validation passes.	Confirm the initial recurring transaction settled successfully and the recurring_token has not expired or been revoked.
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.
101000	Payment does not exist.	Status lookup	GET_TRANS_STATUS by payment_id with an unknown ID.	Verify the payment_id is correct and the payment was created successfully.
101000	Order does not exist.	Status lookup	GET_TRANS_STATUS by order_id with an unknown ID.	Verify the order_id.
101000	Transaction does not exist.	Status lookup	S2S CARD GET_TRANS_STATUS by trans_id with an unknown ID.	Verify the trans_id.
101000	Transaction does not exist.	Not found (CAPTURE)	S2S CARD CAPTURE against an unknown trans_id. Same wording as the status-lookup row above; client-side discrimination must use the request action field, not the message.	Verify the trans_id of the original authentication; ensure it has not already been captured or voided.

Breaking change in 6.7.0

101000 was added in changelog. Before 6.7.0, status-lookup not-found cases returned 100000 with the generic This value is not correct. message. If your integration matches on error_code to detect not-found state, update it to 101000.

---

Payment processing errors

Returned by the routing, builder, and flow stages after validation passes.

203xxx: Currency rates

Error code	Error message	Possible reason	How to fix
203001	Invalid commission settings: total amount less than zero.	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.	ECB rate feed lacks the configured base currency.	Use a supported ECB base currency (e.g., EUR) or switch the rate provider.
203003	Base Currency not found in Bank-Ua XML.	Ukrainian bank rate feed missing the base currency.	Verify the base currency is available in the Bank-Ua feed.
203004	Currency rate not found.	Exchange rate for the currency pair is unavailable.	Check the currency pair is supported; update rate feed configuration.
203005	Currency not found.	Currency code does not exist in the system.	Use a valid ISO 4217 currency code.
203006	Base Currency not found in CurrencyScoop service.	CurrencyScoop feed lacks the base currency.	Verify CurrencyScoop config or change the base currency.

240001 and 204xxx: Traffic balancer / routing

Error code	Error message	Possible reason	How to fix
240001	Not available action. Check MID configuration.	Requested action is not enabled for the assigned MID.	Enable the action in MID configuration.
204001	Merchant mapping not found for current channel.	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.	No active mappings / MIDs match transaction parameters.	Ensure at least one active merchant mapping or MID is configured.
204003	Payment type not supported.	Payment type (e.g., recurring) not enabled for the MID.	Enable the required payment type in MID settings.
204004	Payment method not supported.	Payment method not supported by the MID.	Add the required method to the MID configuration.
204005	Payment action not supported.	Action (capture, refund, etc.) is not enabled.	Enable the action in MID settings.
204006	Payment system/brand not supported.	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.	Daily limit missing or reached.	Set or increase the daily MID limit; or wait until the next day.
204008	Merchant mapping limit is not set or exceeded.	Merchant mapping limit missing or exceeded.	Update the merchant mapping limit configuration.
204009	Payment type not found.	Payment type ID does not exist.	Use a valid, configured payment type.
204010	Payment method not found.	Payment method ID does not exist.	Use a valid payment method; check configuration.
204011	Payment system/brand not found.	Card scheme identifier not recognised.	Verify the payment system / brand value in the request.
204012	Payment currency not found.	Currency not configured for this merchant / MID.	Add the currency to MID config or use a supported currency.
204013	Payment action not found.	Requested action code does not exist.	Use a valid action code.
204014	Month MID limit is exceeded.	Monthly processing limit reached.	Request a limit increase from the acquirer or wait for the new month.
204015	Week Merchant mapping limit is exceeded.	Weekly mapping limit reached.	Increase the weekly limit or wait for the new week.
204016	Payment currency not supported.	Currency not enabled for this MID.	Enable the currency in MID settings or use a supported currency.
204017	Payment amount after exchange equals 0.	Currency conversion results in zero (very small amount).	Increase the transaction amount or review conversion settings.

205xxx: Payment builders

Error code	Error message	Possible reason	How to fix
205001	Merchant mappings not found.	No merchant mapping exists for the given parameters.	Create the required merchant mapping in admin.
205002	Recurring is not supported by specified initial payment.	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.	merchant_key does not correspond to an existing merchant.	Verify the merchant_key in your request credentials.
205004	Payment not found.	Referenced payment ID does not exist.	Check the payment_id; confirm it was created successfully.
205005	Card token is invalid or not found.	Token does not exist or is malformed.	Re-tokenize the card or verify the token value.
205006	Card token is expired.	Token has passed its expiry.	Generate a new card token.
205007	Card token is not accessible.	Merchant is not authorised to use this token.	Use a token belonging to this merchant, or re-tokenize.
205008	This order is scheduled already.	A schedule already exists for this order_id.	Use a different order_id or manage the existing schedule.

208xxx and 209xxx and 210xxx: Payment flow

Error code	Error message	Possible reason	How to fix
208002	Not acceptable to request the 3DS for payment not in 3DS status.	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.	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.	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.	Refund on an unsettled payment.	Wait for the payment to reach settled status before refunding.
208006	Not acceptable to request the refund for amount bigger than payment amount.	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.	Reversal on a non-pending payment.	Reverse only pending / authorised payments.
208008	Not acceptable to request the reversal for amount bigger than payment amount.	Reversal amount exceeds payment amount.	Reversal must not exceed the original amount.
208009	Not acceptable to request the reversal for partial amount.	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.	Chargeback amount exceeds original payment.	Chargeback amount must be less than or equal to the original payment amount.
208011	Not acceptable to request the chargeback for date less than payment's create date.	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.	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.	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.	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.	Void blocked by existing partial refunds.	A payment that has been partially refunded cannot be voided.
209001	Affected payment not found.	Referenced original payment does not exist.	Verify the payment ID used in the operation.
209002	Affected transaction not found.	Referenced transaction ID does not exist.	Check the transaction ID and confirm it was created.
210001	Payment already in process.	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.	Connector does not support API-based refunds.	Issue refunds through the connector admin portal.

220xxx: Test transactions

Error code	Error message	Possible reason	How to fix
220002	Use merchant test key.	Live merchant key used in the sandbox environment.	Use the merchant test key for sandbox transactions.

230xxx: Payment commission

Error code	Error message	Possible reason	How to fix
230001	Invalid commission settings: total amount less than zero.	Commission config produces a negative total.	Fix commission settings so fees do not exceed the transaction amount.

Gateway errors (HTTP 400)

Code	Message	When	Fix
400	Duplicate request.	An identical request was processed recently.	Generate a new order.number for a new payment intent.
400	Previous payment not completed.	A prior payment for this order.number is still in flight.	Wait for the previous payment to reach a terminal state, or void it.

info

Gateway errors apply only for S2S Protocols.

---

See also

• Changelog for the release where each new code was introduced.
• Errors and validation for the Checkout-specific narrative version (same codes, in-context).