Error Reference Guide
This guide lists application error codes, constants, and user-facing messages, categorized by functional domain.
Identity & Authentication
Errors related to access tokens, account verification, and permissions.
| Code | Constant | Description | HTTP Status |
|---|---|---|---|
| 102 | PROCESS_TOKEN_REQUIRED | The process token is required | 401 |
| 103 | TOKEN_EXPIRED | The token has expired | 401 |
| 114 | TOKEN_IS_NOT_VALID | The token is not valid | 401 |
| 119 | ACCOUNT_NOT_VERIFIED | The account is not verified | 403 |
| 120 | ACCOUNT_NOT_FOUND | The account does not exist | 404 |
| 152 | TOKEN_NOT_FOUND | The token does not exist | 404 |
| 228 | TRANSACTION_UNAUTHORIZED | The transaction does not belong to your account | 403 |
| 350 | CARD_TOKEN_EXPIRED | The card token has expired | 422 |
Payment Processing & Card Validation
Errors related to the standard transaction lifecycle, card data validation, and gateway responses.
| Code | Constant | Description | HTTP Status |
|---|---|---|---|
| 100 | ORDER_PROCESSED | The order has already been processed | 409 |
| 101 | CURRENCY_NOT_AVAILABLE_IN_PAYMENT_METHOD | The currency is not available for this payment method | 400 |
| 104 | ORDER_NOT_FOUND | The order does not exist | 404 |
| 105 | TRANSACTION_BLOCKED | The transaction cannot be processed | 422 |
| 106 | AUTHORIZATION_NOT_FOUND | The authorization does not exist | 404 |
| 107 | AUTHORIZATION_NOT_ACTIVE | The authorization is not active | 400 |
| 108 | PAYMENT_METHOD_DEACTIVATED_BY_SELLER | The payment method is deactivated by seller | 403 |
| 109 | PAYMENT_METHOD_NOT_ACTIVE | The payment method is not active | 403 |
| 110 | PAYMENT_METHOD_NOT_AVAIALABLE | The payment method is not available | 503 |
| 111 | PAYMENT_METHOD_NOT_FOUND | The payment method does not exist | 404 |
| 112 | CARD_NOT_FOUND | The card does not exist | 404 |
| 113 | PAYMENT_METHOD_NOT_KEYS | The payment method does not have keys | 500 |
| 115 | DYNAMIC_CVC_REQUIRED | Dynamic CVC is required for this card | 422 |
| 116 | LINK_NOT_ACTIVE | This link is not active | 422 |
| 118 | CARD_INVALID_FOR_SANDBOX | The card is invalid for sandbox | 422 |
| 121 | ACTIVITY_NOT_FOUND | The activity does not exist | 404 |
| 122 | AMOUNT_MAX_ALLOWED | The amount exceeds the maximum allowed | 400 |
| 123 | AMOUNT_MIN_ALLOWED | The amount is less than the minimum allowed | 400 |
| 126 | CARD_NUMBER_INVALID | The card number is invalid | 400 |
| 127 | CARD_TYPE_INVALID | The card type is invalid | 400 |
| 130 | AFILIATION_BRAND_ERROR | The type of card does not correspond to the membership | 400 |
| 131 | CVC_INVALID | Incorrect security code (CVV) | 400 |
| 132 | TRANSACTION_NO_APPROVED | The transaction was not approved | 422 |
| 133 | REFUND_NOT_AVAILABLE | The refund is not available | 400 |
| 134 | CARD_TRY_OTHER | Problem processing payment, please try another card | 422 |
| 135 | CARD_EXPIRED | The card has already expired | 422 |
| 136 | INSUFFICIENT_FUNDS | Insufficient funds in the account for the payment | 422 |
| 137 | TRANSACTION_TRY_AGAIN | Problem processing payment, please try again | 422 |
| 138 | CARD_NOT_ACTIVE | The card is not active | 422 |
| 139 | TRANSACTION_REJECTED_BY_BANK | Transaction rejected by your bank | 422 |
| 140 | TRANSACTION_ALREADY_REFUNDED | The transaction has already been refunded | 409 |
| 142 | ORDER_AMOUNT_NOT_MATCH | The order amount does not match the payment amount | 422 |
| 150 | PAYMENT_METHOD_EXISTS | The payment method already exists | 409 |
| 151 | PAYMENT_METHOD_LIMIT_EXCEEDED | You have exceeded the limit of allowed payment methods | 422 |
| 167 | ORDER_ALREADY_EXISTS | The order already exists | 409 |
| 168 | PAYMENT_PROCESSING_FAILED | The payment could not be processed | 422 |
| 170 | TEMPLATE_NOT_FOUND | The template does not exist | 404 |
| 171 | CARD_ALREADY_EXISTS | The card already exists | 409 |
| 210 | CARD_IS_NOT_VALID_FOR_SANDBOX | The card is not valid for sandbox | 422 |
| 211 | CARD_IS_VALID_FOR_SANDBOX | The card is valid only for sandbox | 422 |
| 212 | TIMEOUT_ORDER_PROCESS | The operation took too long to complete. Please try again | 424 |
| 213 | NO_ALTERNATIVE_VERIFIED_PAYMENT_METHOD_FOUND | No alternative verified payment method found | 404 |
| 214 | DUPLICATE_EMAIL_OR_PHONE | The email or phone already exists | 409 |
| 216 | CARD_NUMBER_REQUIRED | The card number is required | 400 |
| 217 | BIN_NUMBER_REQUIRED | The bin number is required | 400 |
| 218 | BIN_NUMBER_TYPE | The bin number must be of type string | 400 |
MSI (Interest Free Months)
Errors specific to installment plan configurations and validation.
| Code | Constant | Description | HTTP Status |
|---|---|---|---|
| 128 | IFM_NOT_AVAILABLE | Interest free months is not available | 400 |
| 129 | IFM_DATES_INVALID | Interest free months dates are invalid | 400 |
| 153 | MSI_INVALID_TYPE_NUMBER_OF_INSTALLMENTS | Selected type not supported for number of interest free months | 400 |
| 154 | MSI_CONFIG_NOT_FOUND | Interest free months configuration not found | 400 |
| 155 | MSI_INVALID_CARD_NATURE | Card must be credit for interest free months | 400 |
| 156 | MSI_INVALID_CURRENCY | Currency not supported for interest free months | 400 |
| 157 | MSI_INVALID_INSTITUTION_NAME | Institution name not supported for interest free months | 400 |
| 158 | MSI_INVALID_NUMBER_OF_INSTALLMENTS | Number of installments not supported for interest free months | 400 |
| 159 | MSI_INVALID_CARD_BRAND | Card brand must be VISA, Mastercard or American Express | 400 |
| 160 | MSI_COMMISSION_NOT_FOUND | Commission not found for selected number of interest free months | 400 |
| 161 | MSI_INVALID_MINIMUM_AMOUNT | Amount must be greater than the minimum amount for the selected interest free months | 400 |
| 162 | MSI_INVALID_MAXIMUM_AMOUNT | Amount must be less than the maximum amount for the selected interest free months | 400 |
| 163 | MSI_INVALID_AMOUNT_TYPE | Selected Amount must be a number | 400 |
| 164 | MSI_DEFAULT_NOT_FOUND | Default interest free months configuration not found | 400 |
| 165 | MSI_INVALID_DEFAULT_CONFIG | Invalid default interest free months configuration | 400 |
| 166 | MSI_CONFIG_NOT_ACTIVE | Interest free months configuration is not active for this account | 400 |
| 220 | BBVA_INSTALLMENT_NOT_ALLOWED | Number of installments not allowed for BBVA | 400 |
Subscriptions & Recurring Billing
Errors related to subscription plans, recurring payments, and card associations.
| Code | Constant | Description | HTTP Status |
|---|---|---|---|
| 200 | SUBSCRIPTION_NOT_FOUND | The subscription does not exist | 404 |
| 201 | SUBSCRIPTION_CANCELLED | The subscription is cancelled | 422 |
| 202 | SUBSCRIPTION_CARDS_NOT_FOUND | Any of the cards do not exist | 404 |
| 203 | SUBSCRIPTION_FORBIDDEN | The subscription does not exist | 403 |
| 204 | SUBSCRIPTION_PAYMENT_METHOD_ASSOCIATED | Payment method already associated | 409 |
| 205 | SUBSCRIPTION_INVITATION_ALREADY_SENT | Invitation link already sent | 409 |
| 206 | SUBSCRIPTION_NOT_ACTIVE | The subscription does not exist or is not active | 404 |
| 207 | SUBSCRIPTION_NO_CARDS_FOR_PAYMENT | The subscription does not have cards to process the payment | 422 |
| 208 | WITHDRAWALS_LIMIT_EXCEEDED | Withdrawals limit exceeded | 422 |
| 209 | SUBSCRIPTION_INVITATION_LIMIT_REACHED | Subscription invitation limit reached | 422 |
| 221 | SUBSCRIPTION_CARD_ALREADY_ADDED | The card is already added to the subscription | 409 |
| 226 | SUBSCRIPTION_COMMITMENT_ACTIVE | You cannot cancel this subscription during the commitment period | 403 |
| 227 | SUBSCRIPTION_STATUS_CHANGE_NOT_ALLOWED | You are not allowed to change the subscription status | 403 |
Bank Transfers, Direct Debits & CLABE
Errors related to SPEI references, bank connectivity, and Direct Debit workflows.
| Code | Constant | Description | HTTP Status |
|---|---|---|---|
| 141 | TRANSFER_REFERENCE_NOT_CREATED | Problem creating payment reference, please try again | 500 |
| 143 | BANK_NOT_FOUND | The bank does not exist | 404 |
| 144 | REFERENCE_NOT_FOUND | The reference does not exist | 404 |
| 145 | REFERENCE_EXPIRED | The reference has expired | 422 |
| 146 | REFERENCE_ALREADY_EXISTS | The reference already exists | 409 |
| 147 | CUSTOMER_NOT_FOUND | The customer does not exist | 404 |
| 148 | CLABE_NOT_FOUND | The clabe does not exist | 404 |
| 215 | UNABLE_TO_ESTABLISH_COMMUNICATION_WITH_BANK | Unable to establish communication with the bank | 424 |
| 222 | PAYMENT_FAILED_ACCOUNT_INACTIVE_MESSAGE | Your payment could not be processed because your account is inactive. | 403 |
| 223 | CLABE_IS_BLOCKED | The clabe is blocked, please contact support | 403 |
| 224 | EMAIL_OR_PHONE_IS_REQUIRED | The email or phone is required | 400 |
| 229 | CUSTOMER_CLABE_NOT_FOUND | The customer clabe does not exist | 404 |
| 230 | DIRECT_DEBIT_NOT_FOUND | The direct debit does not exist | 404 |
| 231 | CLABE_ALREADY_EXISTS | The CLABE already exists | 409 |
| 232 | CLABE_INVALID_FORMAT | The CLABE must be exactly 18 digits | 400 |
| 233 | CLABE_INVALID_CHARACTERS | The CLABE must contain only numbers | 400 |
| 234 | DIRECT_DEBIT_FAILED_TO_SET_NEXT_PAYMENT_DATE | Failed to set the next payment date for the direct debit | 400 |
| 235 | DIRECT_DEBIT_INVITATION_LIMIT_REACHED | Direct debit invitation limit reached | 409 |
| 236 | DIRECT_DEBIT_FORBIDDEN | You do not have permission to access this direct debit | 403 |
| 237 | DIRECT_DEBIT_ALREADY_PROCESSED | The direct debit has already been processed | 400 |
| 238 | CLABE_ALREADY_ACTIVE | The CLABE is already active | 409 |
| 238 | CUSTOMER_CLABE_NOT_FOUND_FOR_CUSTOMER | Customer CLABE not found for the specified customer, please create it first | 404 |
| 340 | CLIENT_NOT_SAVED | External user ID is required for CLABE verification | 400 |
| 341 | CLABE_VERIFICATION_CUSTOMER_CLABE_NOT_FOUND | Customer CLABE not found for verification | 404 |
| 341 | CLABE_VERIFICATION_EXTERNAL_USER_ID_REQUIRED | Missing externalUserId in webhook event | 400 |
| 342 | CLABE_VERIFICATION_ACCOUNT_NOT_FOUND | Account not found for CLABE verification | 404 |
| 342 | CLABE_VERIFICATION_UPDATE_FAILED | Error updating CLABE verification status | 500 |
| 343 | CLABE_VERIFICATION_INVALID_TYPE | Invalid verification type for CLABE | 400 |
| 343 | CLABE_VERIFICATION_REJECTED | CLABE verification was rejected | 422 |
| 344 | CLABE_VERIFICATION_CLIENT_SAVE_ERROR | Error saving client info locally | 500 |
| 344 | CLABE_VERIFICATION_EVENT_IGNORED | Event ignored - not a verification completion event | 200 |
| 345 | CLABE_VERIFICATION_WEBHOOK_ERROR | Error processing CLABE verification webhook | 500 |
POS, Terminals & Hardware
Errors related to physical Point of Sale devices, registers, and branch configuration.
| Code | Constant | Description | HTTP Status |
|---|---|---|---|
| 300 | POS_INFO_NOT_FOUND | POS information not found | 404 |
| 301 | ACCOUNT_ID_REQUIRED | Account ID is required | 400 |
| 302 | TERMINAL_ID_REQUIRED | Terminal ID is required | 400 |
| 303 | STATUS_REQUIRED | Status is required | 400 |
| 304 | DEVICE_STATUS_UPDATED | Device status updated successfully | 200 |
| 305 | TRANSACTION_ID_REQUIRED | Transaction ID is required | 400 |
| 306 | EMAIL_REQUIRED | Email is required | 400 |
| 307 | TRANSACTION_NOT_FOUND | Transaction not found | 404 |
| 308 | ORDER_NOTIFICATION_SENT | Order notification sent successfully | 200 |
| 309 | TERMINAL_DEVICE_REQUEST_CREATED | Terminal device request created successfully | 201 |
| 310 | TERMINAL_REQUEST_NOT_FOUND | Terminal request not found | 404 |
| 311 | TERMINAL_DEVICE_CREATED | Terminal device created successfully | 201 |
| 312 | TERMINAL_DEVICE_NOT_FOUND | Terminal device not found | 404 |
| 313 | TERMINAL_DEVICE_UPDATED | Terminal device updated successfully | 200 |
| 314 | AUTHORIZATION_NOT_FOUND_FOR_ACCOUNT | Authorization not found for this account | 404 |
| 315 | ACTIVE_POS_NOT_FOUND | Active POS information not found for the given serial number and model | 404 |
| 316 | POS_NOT_FOUND_FOR_ACCOUNT | POS information not found for the given account ID | 404 |
| 317 | INVALID_DEVICE_STATUS | Invalid status. Must be one of: active, inactive, blocked | 400 |
| 318 | DEVICE_NOT_FOUND_OR_NO_PERMISSION | Device not found or you do not have permission to update it | 403 |
| 319 | MISSING_REQUIRED_FIELDS | Missing required fields: model, quantity, or delivery_address | 400 |
| 320 | INVALID_TERMINAL_MODEL | Invalid terminal model | 400 |
| 321 | INVALID_QUANTITY_RANGE | Quantity must be between 1 and 100 | 400 |
| 322 | INVALID_PURCHASE_TYPE | Invalid purchase_type. Must be either "purchase" or "rental" | 400 |
| 323 | MODEL_ID_REQUIRED | model_id is required | 400 |
| 324 | NAME_TRANSLATIONS_REQUIRED | Name translations (en, es) are required | 400 |
| 325 | SHORT_DESCRIPTION_TRANSLATIONS_REQUIRED | Short description translations (en, es) are required | 400 |
| 326 | MANUFACTURER_MODEL_NAME_REQUIRED | Manufacturer model name is required | 400 |
| 327 | PRICING_REQUIRED | Pricing is required | 400 |
| 328 | CATEGORY_REQUIRED | Category is required | 400 |
| 329 | FORBIDDEN_OPERATION | You are not allowed to perform this operation | 403 |
| 330 | ORDER_ID_REQUIRED | Order ID is required | 400 |
| 332 | TRANSACTION_OR_ORDER_ID_REQUIRED | Either transaction_id or order_id is required | 400 |
| 352 | SALES_REGISTER_NOT_FOUND | Sales register not found | 404 |
| 353 | NO_TERMINAL_LINKED_TO_REGISTER | No terminal linked to this register | 400 |
| 354 | TERMINAL_NOT_ENABLED_FOR_POINT_OF_SALE | Terminal is not enabled for Point of Sale | 400 |
| 355 | TERMINAL_ALREADY_LINKED_TO_REGISTER | Terminal is already linked to another register | 400 |
| 356 | SALES_REGISTER_NOT_LINKED_TO_POS_TERMINAL_OR_BRANCH | The sales register is not linked to a POS terminal or branch | 400 |
| 357 | REGISTER_NUMBER_ALREADY_EXISTS_IN_BRANCH | Register number already exists in this branch | 400 |
| 358 | BRANCH_NOT_FOUND | Branch not found | 404 |
| 359 | CANNOT_DELETE_POS_BRANCH_WITH_ACTIVE_SALES_REGISTERS | Cannot delete pos branch with active sales registers | 400 |
| 360 | EXTERNAL_ID_ALREADY_EXISTS_FOR_ACCOUNT | External ID already exists for this account | 400 |
Billing & Invoicing
Errors related to tax invoices and billing providers.
| Code | Constant | Description | HTTP Status |
|---|---|---|---|
| 117 | PRICING_NOT_FOUND | The pricing does not exist | 404 |
| 333 | BILLING_UPDATED | Billing updated successfully | 200 |
| 334 | BILLING_NOT_FOUND | The billing does not exist | 404 |
| 335 | FILE_NOT_FOUND | The file does not exist | 404 |
| 336 | BILLING_REQUEST_NOT_SUPPORTED | Request not supported | 409 |
| 337 | PROVIDER_CONNECTION_SUCCESS | Connection to billing provider is successful | 200 |
| 338 | PROVIDER_CONNECTION_FAILED | Could not connect to the billing provider | 409 |
| 339 | MISSING_NIF_KEY | NIF API Key is required for this operation | 500 |
| 347 | INVALID_SURCHARGE_RATE | The surcharge rate must be a valid number | 400 |
| 348 | MISSING_LOCALES_OR_COUNTRY | Locales in body request and/or country in query params are required | 400 |
| 351 | ISSUER_NIF_INFO_NOT_FOUND | Could not retrieve issuer information from NIF | 500 |
External Integrations & 3D Secure
Errors arising from third-party services (Shopify, Sumsub) and 3DS verification.
| Code | Constant | Description | HTTP Status |
|---|---|---|---|
| 124 | GATEWAY_INTEGRATION_ERROR | Problem in integration with the processor | 502 |
| 125 | GATEWAY_INTEGRATION_CONFIGURATION_ERROR | Problem in configuration with the processor | 500 |
| 149 | THREEDS_INTEGRATION_REQUIRED | 3DSecure is required for this card | 422 |
| 169 | THREEDS_UNSUCCESSFUL | The 3D Secure authentication was unsuccessful | 422 |
| 172 | RESOLVE_PAYMENT_SESSION_SHOPIFY | Error in the service to resolve the payment session to Shopify | 424 |
| 173 | REJECTED_PAYMENT_SESSION_SHOPIFY | Error in the service to rejected the payment session to Shopify | 424 |
| 174 | REDIRECT_PAYMENT_SESSION_SHOPIFY | Error in the service to redirect the payment session to Shopify | 424 |
| 175 | REJECTED_REFUND_SHOPIFY | Error in the service to rejected the refund session to Shopify | 424 |
| 176 | RESOLVE_REFUND_SHOPIFY | Error in the service to resolve the refund session to Shopify | 424 |
| 219 | ID_NOT_VALID | The ID is not valid | 400 |
| 225 | PAYMENT_METHOD_ASSOCIATED_WITH_LEVEL_3_ACTIVATION | This payment method is associated with a level 3 activation | 403 |
| 346 | SUMSUB_SDK_LINK_GENERATION_FAILED | Failed to generate Sumsub Web SDK link | 500 |
| 349 | THREEDS_NOT_FOUND | The 3D Secure does not exist | 404 |
Updated 8 days ago