> ## Documentation Index > Fetch the complete documentation index at: https://docs.jupico.com/llms.txt > Use this file to discover all available pages before exploring further. # Error Codes > Catalog of every stable error code returned by the Jupico API, with cause and remediation. 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](/api-reference/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](mailto:support@jupico.com).