Error Codes

Jupico returns a machine-readable identifier in the code field of every response body. Branch on code — the human-readable message is for display and may change.

For payment flows, some declined outcomes return HTTP 200 with success: false. Always inspect both the HTTP status and the response body. See Status Codes.

General

HTTP	Code	Message	Recommended handling
`400`	`invalid_payload`	Invalid payload.	Validate required fields, types, and schema before retrying.
`404`	`wrong_url`	Requested resource not found.	Confirm the endpoint path and resource ID.
`403`	`forbidden`	Forbidden.	Confirm permissions and account access.
`503`	`service_unavailable`	External service unavailable, try again later.	Retry with backoff.
`500`	`internal_server_error`	Internal server error.	Log request details and use rollback handling for transactions where applicable.

Authorization

HTTP	Code	Message
`401`	`auth_invalid_submerchant`	SubMerchant not found or inactive.
`401`	`auth_invalid_role`	API user does not have required permissions.
`401`	`auth_header_not_present`	Authorization header missing.
`401`	`auth_invalid_api_token`	Invalid api token.
`401`	`auth_invalid_api_user`	API user not active.
`401`	`auth_invalid_facilitator`	Facilitator not found or inactive.
`401`	`auth_invalid_product`	Product not found or inactive.
`401`	`auth_invalid_content_type`	Invalid content type. Expected `application/json`.
`401`	`auth_invalid_feature`	Submerchant feature is invalid.
`401`	`auth_feature_disabled`	Submerchant feature disabled.
`401`	`auth_service_provider_feature_disabled`	Service provider feature disabled.
`401`	`auth_submerchant_feature_disabled`	Submerchant feature disabled.

Card transaction declines

These outcomes typically represent user-correctable or issuer-driven declines.

HTTP	Code	Message
`200`	`tx_cc_declined`	The card is declined.
`200`	`tx_cc_declined_insufficient_funds`	The card has insufficient funds.
`200`	`tx_cc_declined_do_not_honor`	The card is declined for an unknown reason.
`200`	`tx_cc_declined_transaction_not_allowed`	The card is declined for this transaction type.
`200`	`tx_cc_declined_stolen_card`	The card has been reported stolen.
`200`	`tx_cc_declined_fraudulent`	The payment is suspected as fraudulent.
`200`	`tx_cc_declined_incorrect_cvc`	The card security code is incorrect.
`200`	`tx_cc_declined_incorrect_zip`	The card postal code is incorrect.
`200`	`tx_cc_declined_incorrect_number`	The card number is incorrect.
`200`	`tx_cc_declined_amount_exeeded`	Amount exceeded submerchant limit.
`200`	`tx_cc_declined_expired_card`	The card is expired.
`200`	`tx_cc_declined_pick_up_card`	Issuer wants to retrieve the card.
`200`	`tx_cc_declined_referral_call_issuer`	Cardholder should contact issuer.
`200`	`tx_cc_declined_incorrect_address`	The card address is incorrect.
`200`	`tx_cc_declined_risk_profile`	Transaction declined due to high risk.
`200`	`tx_cc_declined_lost_card`	The card is reported lost.
`200`	`tx_cc_declined_restricted_card`	The card is restricted.
`200`	`tx_cc_declined_unsupported_card`	Unsupported card.

Card transaction errors

HTTP	Code	Message
`400`	`tx_cc_invalid_avs`	AVS failed.
`400`	`tx_cc_duplicate`	Transaction duplicated.
`400`	`tx_cc_invalid_data`	Invalid credit card data sent.
`400`	`tx_cc_not_auth`	Transaction was not authorized and was rejected.
`400`	`tx_cc_invalid_account`	Account is invalid or inactive.
`400`	`tx_cc_token_corrupted`	Credit card token corrupted; tokenize again.
`400`	`tx_cc_token_not_found`	Credit card token not found.
`400`	`tx_cc_already_voided`	Transaction already voided.
`400`	`tx_cc_not_found`	Transaction not found.
`400`	`tx_cc_reversal_failed`	Reversal failed.
`400`	`tx_cc_error`	Generic card transaction error.
`400`	`tx_cc_invalid_status`	Invalid transaction status.
`400`	`tx_cc_invalid_amount`	Invalid amount for related transaction.
`400`	`tx_cc_invalid_operation`	Operation is invalid for the related transaction.
`400`	`tx_cc_already_refunded`	Transaction already refunded.
`400`	`tx_cc_disputed`	Transaction disputed.
`400`	`tx_cc_void_unavailable`	Unable to void; related transaction expired after 25 minutes.
`400`	`tx_cc_invalid_taxWithHold`	Parent and related transaction `taxWithHold` should match.
`400`	`tx_cc_invalid_refund_taxAmountRelease`	Refund `taxAmountRelease` cannot exceed the parent transaction tax amount.
`400`	`tx_cc_taxAmount_exceeded`	Tax amount exceeded.
`400`	`tx_cc_retry`	Retry is allowed.
`400`	`tx_cc_do_not_retry`	Do not retry.

eCheck transaction errors

HTTP	Code	Message
`400`	`tx_echeck_declined_amount_exeeded`	Amount exceeded submerchant limit.
`400`	`tx_echeck_not_found`	eCheck transaction not found.
`400`	`tx_echeck_duplicate`	Transaction duplicated.
`400`	`tx_echeck_invalid_status`	Invalid transaction status.
`400`	`tx_echeck_invalid_amount`	Invalid amount for related transaction.
`400`	`tx_echeck_invalid_operation`	Operation is invalid for the related transaction.
`400`	`tx_echeck_already_refunded`	Transaction already refunded.
`400`	`tx_echeck_reversal_failed`	Reversal failed.
`400`	`tx_echeck_token_not_found`	Bank account token not found.
`400`	`tx_echeck_token_corrupted`	Bank account token corrupted; tokenize again.
`400`	`tx_echeck_error`	Generic eCheck transaction error.
`400`	`tx_echeck_invalid_taxWithHold`	Parent and related transaction `taxWithHold` should match.
`400`	`tx_echeck_invalid_refund_taxAmountRelease`	Refund `taxAmountRelease` cannot exceed the parent transaction tax amount.
`400`	`tx_echeck_refund_unavailable`	Refund is not available.
`400`	`tx_echeck_invalid_routing_number`	Bank account routing number is invalid.

Tokenization

HTTP	Code	Message
`200`	`tkn_cc_expired_credit_card`	The card is expired.
`200`	`tkn_cc_invalid_expiration_year`	Invalid expiration year. Expected `YY` or `YYYY`.
`200`	`tkn_cc_invalid_expiration_month`	Invalid expiration month. Expected `M` or `MM`.
`200`	`tkn_cc_invalid_expiration_date`	The card is expired.
`200`	`tkn_cc_invalid_number`	The card number is invalid.
`200`	`tkn_cc_invalid_security_code`	The security code is invalid.
`200`	`tkn_cc_unsupported_card_type`	Unsupported card type.
`200`	`tkn_cc_live_mode_test`	Test card used in live mode.
`200`	`tkn_cc_insufficient_funds`	The card has insufficient funds.
`200`	`tkn_cc_do_not_honor`	The card was declined.
`400`	`tkn_invalid_public_key`	Invalid submerchant public key.
`400`	`tkn_cc_not_tokenizable`	Credit card not tokenizable.
`400`	`tkn_error`	Tokenization error.
`401`	`tkn_oneTimeToken_expired`	One-time token expired.
`429`	`tkn_cc_too_many_requests`	Too many requests.
`400`	`tkn_echeck_invalid_account`	Invalid bank account.

Payouts

HTTP	Code	Message
`400`	`payouts_invalid_status`	Invalid payout status.
`400`	`payouts_not_found`	Payout not found.
`400`	`payouts_insufficient_funds`	Payout funds insufficient.
`400`	`payouts_invalid_bank_account`	Bank account not found or inactive.
`400`	`payouts_invalid_mode`	Invalid payout mode; expected dynamic.
`400`	`payouts_debit_invalid_amount`	Debit amount must be negative.
`400`	`payouts_credit_invalid_amount`	Credit amount must be positive.
`400`	`payouts_not_manual_mode`	Payout is not manual.
`400`	`payouts_account_not_found`	Account does not exist.

Provisioning

HTTP	Code	Message
`400`	`provisioning_application_invalid`	Submerchant application not found or inactive.
`400`	`provisioning_application_missing_owner`	Application type requires at least one owner.
`400`	`provisioning_ownershiptype_single_owner`	Ownership type must have a single owner.
`400`	`provisioning_ownershiptype_invalid_owner`	Owners are not valid for this application type.
`400`	`provisioning_ownershiptype_invalid_identity`	Invalid ownership type for this identity type.
`400`	`provisioning_ownership_invalid_percentage`	Sum of ownership percentages must be between 76% and 100%.
`400`	`provisioning_bank_account_already_tokenized`	Bank account already tokenized.
`400`	`provisioning_bank_account_invalid_status`	Bank account invalid status.
`400`	`provisioning_bank_account_not_found`	Bank account not found.
`400`	`provisioning_invalid_identity_type`	Invalid identity type.
`400`	`provisioning_invite_invalid`	Invite not found or inactive.

Hosted products

Area	HTTP	Code	Message
Hosted session	`400`	`hosted_session_not_found`	Hosted session not found.
Hosted session	`400`	`hosted_session_invalid_status`	Hosted session has invalid status.
Hosted session	`400`	`hosted_session_payment_link_invalid_status`	Payment link has invalid status.
Invoice	`400`	`invoice_invalid`	Invoice not found or inactive.
Invoice	`400`	`invoice_invalid_status`	Invoice has invalid status.
Invoice	`400`	`invoice_amount_exeeded`	Amount exceeded submerchant limit.
Invoice	`400`	`invoice_invalid_items_amount`	Total amount of items is invalid.
Invoice	`400`	`invoice_update_invalid_status`	Status can only change from `Draft` to `Created` on update.
Payment link	`400`	`payment_link_invalid`	Payment link not found or inactive.
Payment link	`400`	`payment_link_invalid_status`	Payment link has invalid status.
Payment link	`400`	`payment_link_invalid_total_amount`	Total amount is invalid.
Payment link	`400`	`payment_link_amount_exeeded`	Amount exceeded submerchant limit.
Checkout	`400`	`checkout_invalid`	Checkout not found or inactive.
Checkout	`400`	`checkout_invalid_status`	Checkout has invalid status.
Checkout	`400`	`checkout_invalid_total_amount`	Total amount of items is invalid.
Checkout	`400`	`checkout_amount_exeeded`	Amount exceeded submerchant limit.

Subscriptions

HTTP	Code	Message
`400`	`subscription_error`	Error on subscription.
`400`	`subscription_plan_invalid`	Plan not found or inactive.
`400`	`subscription_plan_duplicated_name`	Plan name is already in use.
`400`	`subscription_invalid`	Subscription not found or inactive.
`400`	`subscription_schedule_not_found`	Schedule does not exist on subscription.
`400`	`subscription_invalid_pricing_model`	Wrong schedule pricing model type.
`400`	`subscription_invalid_pricing_model_params`	Invalid pricing model parameters.
`400`	`subscription_active_subscribers`	Plan has active subscribers.
`400`	`subscription_invalid_schedule`	Schedule ID does not exist on the plan.

Other

Area	HTTP	Code	Message
Product	`400`	`product_invalid`	Product not found or inactive.
Product	`400`	`product_invalid_mcc`	Invalid `mccCode`.
Product	`400`	`product_invalid_ownershiptype`	Invalid ownership type.
Customer	`400`	`customer_invalid`	Customer not found or inactive.
Customer	`400`	`customer_email_duplicated`	Customer with this email already exists.
Customer	`400`	`customer_phone_duplicated`	Customer with this phone number already exists.
User	`400`	`api_user_invalid`	API user not found or inactive.
Bank account	`400`	`bankaccount_invalid_routing_number`	Bank account routing number is invalid.
Bank account	`400`	`bankaccount_invalid_account_number`	Bank account account number is invalid.
Risk	`400`	`risk_alert_not_found`	Alert not found.
BIN lookup	`400`	`binlookup_bin_number_not_match`	BIN number not found.

Not sure what you got?

If you receive a code that isn’t listed here, share the value and the associated X-Request-ID with support@jupico.com.

API Overview

API Reference

Resources

General

Authorization

Card transaction declines

Card transaction errors

eCheck transaction errors

Tokenization

Payouts

Provisioning

Hosted products

Subscriptions

Other

Not sure what you got?

​General

​Authorization

​Card transaction declines

​Card transaction errors

​eCheck transaction errors

​Tokenization

​Payouts

​Provisioning

​Hosted products

​Subscriptions

​Other

​Not sure what you got?

General

Authorization

Card transaction declines

Card transaction errors

eCheck transaction errors

Tokenization

Payouts

Provisioning

Hosted products

Subscriptions

Other

Not sure what you got?