Learn how to handle the error codes that may appear in the requests to our endpoints.
Error structure
The API returns an object with two response attributes to show the error in the request.
The response consists of:
- code which represents a Generic code
- description which represents a meaningful error message
{
"error": {
"code": "EMA-1000",
"description": "x-api-key"
},
"data": null
}
Coupons
| Error Code | Error type | Cause | Possible solution |
|---|---|---|---|
| EM-6003 | CuponAlreadyUsedInOrder | The coupon has been applied to the order | Verify whether the coupon has already been applied to the order using the get order by token method. |
| EM-6002 | CuponAlreadyUsed | The Coupon is already used | Check the limit of uses of the coupon or if it is a unique coupon. |
| EM-6001 | CuponNotApplicable | The coupon is expired or does not exist. | Check that the coupon code is valid, has not expired, and is still active. |
| EM-6000 | CuponNotFound | Coupon not found | Verify that the coupon code is in the allowed format and try again. |
| EM-5000 | MerchantUnknown | Unknown error |
Shipping costs
| Error Code | Error type | Cause | Possible solution |
|---|---|---|---|
| EM-4000 | WithoutCoverage | Dispatch location outside coverage area | Check the latitude and longitude of the shipping method and see if it is within the coverage area. |
| EM-4001 | ClosedStore | Closed shop | Check store hours and verify that it is open. |
| EM-5000 | MerchantUnknown | Unknown error | Unknown error, please make a new request or contact support. |
Common API errors
| Error Code | Error type | Cause | Possible solution |
|---|---|---|---|
| EMA-1000 | MissingHeaders | The request header is missing or invalid | Verify that the header is being sent correctly in the request. |
| EMA-1001 | CannotGetMetadata | Cannot get the metadata | Check if the metadata sent in the request has the correct format. |
| EMA-1002 | PayloadError | The request’s payload has failed. | Verify that the request's payload or body is correctly formatted. |
| EMA-1003 | ShippingOptionNotAvailable | Shipping option is not available | Check if the shipping option is valid for those we have available: delivery or pickup. |
| EMA-1004 | OrderAlreadyProcessed | The order has already been processed | Place a new order, as the previous order has already been processed. |
| EMA-1005 | OrderStatusNotValidForTransition | Attempting to change the status of a transaction that is already cancelled, refunded, or completed | Check the current state of the transaction before attempting to change it. |
| EMA-1006 | OrderStateConflicts | The order does not have a defined shipping method | Please make sure you select a valid shipping method before proceeding with the transaction. |
| EMA-1007 | ShippingMethodNotAvailable | Shipping method does not match any available | Review the shipping methods configured for the merchant and select a compatible one. |
| EMA-1008 | ConfigurationOperationConflict | Trade setup does not exist in the database | Verify that the required settings are set correctly. |
| EMA-1009 | InvalidOrderType | Invalid order type | Review the type of order being sent and make sure it is compatible with the configured systems. |
| EMA-2000 | CannotParseData | Error when trying to process or analyze data | Make sure the data sent is in the correct format and meets system requirements. |
| EMA-3000 | ConfigurationNotFound | Configuration not found | The endpoints for merchant integration have not been configured. |
| EMA-3001 | OrderNotFound | Order not found | The Order is not registered in the store; validate that it is correct or that it is within the store. |
| EMA-3002 | DataBaseError | Database error | Try again he transaction later. |
| EMA-3003 | ConfigurationAlreadyExist | An attempt was made to create a trading setup that already exists | Check if the configuration is already registered before trying to create a new one. |
| EMA-4000 | RequestServiceError | The request cannot connect to a service | Verify whether the request is correct. |
| EMA-4001 | RequestServiceTimeout | The request has reached its waiting time to get a response. | Generate another request. |
| EMA-4002 | payerServiceError | Payment methods are not available or the request to the merchant service failed | Make sure that the payment methods are configured correctly or contact suport. |
| EMA-5000 | Unauthorized | The request is not authorized. | X-API-Key is missing in the request header |
| EMA-5001 | InvalidAPIKey | The provided API key is not valid | Review the API key used in the request and replace it with a valid one if necessary. |
| EMA-6000 | RefundError | The refund has failed. | Verify that the body of the request is formatted correctly. |
| EMA-6001 | VoidError | The void request has failed. | Verify that the body of the request is formatted correctly. |
| EMA-6002 | PendingPayment | The order is in pending or processing status | Wait for the order status to update or check the current status before taking further action. |
| EMA-6003 | CaptureError | Error when trying to update an order to capture status | Verify the existence of the order and make sure it meets the criteria to be captured. |
| EMA-6004 | CannotCreateOrder | Could not tokenize or create an order | Make sure that the data provided for creating the order is correct and complete. |
| EMA-6005 | CannotUpdateCustomFields | Failure to validate or update custom fields of an order | Verify that custom fields are correctly defined and compatible with the configured systems. |
| EMA-6006 | CannotGetUserInfo | The request to the business user service failed | Review the connection to the user service and ensure that the requests include the correct parameters. |
| EMA-6007 | CannotGetWebhook | Cannot get the Webhook configuration | Verify that the body of the request is formatted correctly. |
| EMA-6008 | CannotExecuteWebhook | Webhook response with custom fields not configured | Review the webhook configuration |
| EMA-6009 | CannotApplyTemplate | Conflict when trying to apply a template | Review the configured templates. |
| EMA-6010 | ErrorFromMerchant | Error raised due to an error in the merchant API | Verify that the body of the request is formatted correctly. |
| EMA-6011 | CannotUpdateOrder | The order could not be updated | Verify that the body of the request is formatted correctly. |
| EMA-6016 | CannotCancelPurchasedOrder | Failure to send a notification and cancel a purchased order | Review your notification settings and make sure the order meets the criteria to be canceled. |
| EMA-6017 | CannotNotifyPurchasedOrder | Merchant notification settings not available | Properly configure notifications for the merchant before attempting to send alerts or updates. |
| EMA-6018 | Unauthorized | There was a problem with authentication. | Please review the API keys that are currently in use. |
| EMA-6019 | OrderExpired | This order has already expired, so you cannot try to pay it. This error happens when trying to pay an expired order. | You must create a new order. |
| EMA-6020 | CannotExpireOrder | You cannot expire this order because it has either expired or had an associated payment attempt. Special Cases: PIX: an order is allowed to expire when it has no associated payment attempt or the associated payment attempt is pending. | You must create a new order. |
| EMA-7000 | InvalidFileRequest | File request is invalid | Verify that the request includes the correct parameters and formats before resending it. |
| EMA-7001 | InternalErrorRetrievingFiles | Error when trying to recover stored files | Review storage services or configurations to ensure proper recovery. |
| EMA-7002 | InternalErrorRetrievingPresignedURL | Error retrieving pre-signed URLs | Review your pre-signed URL generation settings and make sure your storage system is working properly. |
| EMA-8000 | PaymentLinkRedirectError | Failed to redirect to order token of the payment link | Review the order token and verify that it is correct. |
| EMA-9001 | AttemptsExceededCode | The allowed number of attempts for the transaction has been exceeded | Try again with another card or payment method |
| EMA-9998 | MerchantInternalError | Internal error | Retry the transaction or try another payment processor |
| EMA-9999 | MerchantUnknown | The merchant identifier is not present in the request | Include the merchant identifier in the request or verify the structure of the data sent. |
Payment link
| Error Code | Error type | Cause | Possible solution |
|---|---|---|---|
| EMA-6021 | CannotCreatePaymentLinkTemplate | An error occurred while trying to create the payment link template. | Ensure that the fields included in the payment link request are necessary for its creation. |
| EMA-6022 | CannotGetPaymentLinkTemplate | The system cannot find the requested payment link template. | Verify the payment link ID requested. |
| EMA-6023 | CannotUpdatePaymentLinkTemplate | An error occurred while trying to update the Payment link template. | Verify the required fields requested to update the payment link. |
| EMA-6024 | InvalidStatusTransitionPaymentLinkTemplate | The requested status transition is invalid or does not allow modifications. | Verify that the status is eligible for change or modification before transitioning. |
| EMA-6025 | PaymentLinkTemplateExpired | The payment link template has expired and is no longer valid for use. | Generate a new payment link if needed to continue the operation or edit the expiration date of the current payment link. |
| EMA-6026 | PaymentLinkTemplateLimitExceeded | The maximum allowable uses for the payment link have been exceeded. | Create a new payment link or increase the redemption limit. |
| EMA-6027 | PaymentLinkTemplateCompleted | The payment link template has been completed. | No further action is required. If a new payment is needed, generate a new link. |
| EMA-6028 | PaymentLinkTemplateDisabled | The payment link template has been deactivated and is no longer available. | Verify the link settings and, if necessary, reactivate the link or create a new one. |
| EMA-6029 | PaymentLinkTemplateCancelled | The payment link template has been canceled; the operation cannot continue. | Create a new payment link if a new transaction is required. |
Checkout
| Error Code | Error type | Cause | Possible solution |
|---|---|---|---|
| CHECKOUT-1000 | CheckoutNotReady | Checkout is not ready to start | Verify checkout settings |
| CHECKOUT-1001 | CheckoutNotReadyForShipping | Checkout is not ready for shipping | Verify the shipping method configuration or the shipping rate. |
| CHECKOUT-1002 | CheckoutNotReadyForNotify | Checkout is not ready to notify | Verify that exists only one notification endpoint configured. |
Payments
| Error Code | Error type | Cause | Possible solution |
|---|---|---|---|
| DP-10001 | Err3DSVerifySupport | Problems processing 3DS related data | Verify that the information submitted is complete and correct. Make sure the settings are up to date. |
| DP-10002 | Err3DSAuthorize | Problems authorizing transactions with 3DS | Confirm that the customer's details are correct. Check the authorization method settings. |
| DP-10003 | Err3DSRequiredChallenge | 3DS challenge required error | Try again with another card or payment method. |
| DP-10004 | Err3DSGetStatus | Error checking 3DS status | Try again with another card or payment method. |
| DP-10005 | Err3DSPurchase | Error when making purchases with 3DS | Try again with another card or payment method. |
| DP-10024 | ErrManualReview | Error getting manual review status for a transaction | Confirm the transaction information. |
| DP-10025 | Err3DSChallengeFailed | Payment service provider responds with failure in 3DS challenge | Try again with another card or payment method. |
| DP-3000 | ErrPayload | Error in the payload sent in the request or it’s empty | - Verify that you send the payload. - For Nequi, verify that the phone number is included - For refund transactions, verify that the amount sent is positive |
| DP-3001 | ErrCannotParseData | The data sent cannot be verified or a validation rule has failed | Validate the data payload |
| DP-3002 | ErrRequestServiceError | - The card cannot be tokenized or retrieved - Error in the installments plan | Validate the request information and try again |
| DP-3003 | ErrAmountRequestError | The processor does not support partial refunds | Validate that the amount field matches or is not null in the request |
| DP-4000 | ErrMissingHeaders | The processor does not support partial refunds | Validate that the amounts field match or are not null in the request |
| DP-4001 | ErrUnauthorized | Request header not found | Verify that the header is being sent correctly in the request. |
| DP-4002 | ErrCardTokenForbidden | Request not authorized | Validate the X-API-Key header or check your configuration |
| DP-4003 | ErrStoreCodeValidation | Store code not found | Validate that the store code is not empty or is incorrect |
| DP-4004 | ErrValidation | - The authorization and capture methods are not enabled - For PlacetoPay, the country_iso field is missing | Validate you configuration or check if the country_iso field is not empty |
| DP-4005 | ErrMerchantIDValidation | The merchant code was not found | Check if the merchant code is not empty or incorrect |
| DP-4006 | ErrUserValidation | User information is empty or invalid in the request of the webhook | Check the user information. |
| DP-4007 | ErrParseUuid | The error token has not the correct format | Validate the error token |
| DP-4008 | ErrCardNotFound | The card cannot be retrieved from the token or the number is not correct. | Check the card number in the request or the card token In case you are using card_id, this error means that the card_id is not part of or associated with the user you are using to create the /purchase. |
| DP-4009 | ErrProcessorNotFound | The payment processor does not exist or is not enabled for the merchant | Check in Admin if the payment method is configured. |
| DP-4011 | ErrMerchantStoreConfigNotFound | Merchant store configuration not found | Make sure the store code is correct. |
| DP-4012 | ErrAlreadyExistsInDB | The payment or configuration processor already exists in the database | Verify the data before trying to add new records. |
| DP-4013 | ErrPaymentProcessorNotFound | Payment processor not found | Check the processor data and make sure the identifier is valid. |
| DP-4015 | ErrProcessorNotSupported | The payment processor does not support the operation | Make sure your processor supports the requested method. |
| DP-4016 | ErrCannotFindOperations | The processor does not support the requested operation | Review processor capabilities to ensure compatibility with required operations. |
| DP-4017 | ErrInvalidCard | Problems with the card provided | Verify that the card details are correct and that it is enabled for use. |
| DP-4018 | ErrInvalidCaptureAmount | Attempt to capture an amount greater than authorized | Make sure the amount captured does not exceed what was originally authorized. |
| DP-4019 | ErrTransactionInProcess | Transaction in process | Wait for the current transaction to complete before attempting another operation. |
| DP-4020 | ErrTokenTransactionNotFoundRedis | Error retrieving transaction information | Check that the requested information exists. |
| DP-4022 | ErrProcessorsNotSupportSplit | There are no processors that support split payments | Review your processor settings and make sure at least one allows split payments. |
| DP-4023 | ErrMissingRecipientProcessors | Processors are missing or numbers of recipients and processors do not match | Make sure you configure all recipients and processors necessary to complete the operation. |
| DP-4024 | ErrInvalidCredentials | Incorrect credentials in purchase transactions, authorization, etc. | Confirm that the processor credentials entered are valid. |
| DP-4026 | ErrPurchase | Purchase transaction failure | Verify the transaction details and make sure the system is properly configured to process payments. |
| DP-4027 | ErrAuthorize | Authorization transaction failure | Make sure the customer details are correct and the system supports the authorization method. |
| DP-4028 | ErrCapture | Capture transaction failure | Confirm that the amount to be captured is valid and that the system supports the capture operation. |
| DP-4029 | ErrVoid | Transaction void failure | Verify that the transaction is authorized and can be voided according to system policies. |
| DP-4030 | ErrAuthenticationMissing | Documents or types of documents required for the transaction are missing | Be sure to provide the payer's document number or type |
| DP-4031 | ErrNoProcessorForDynamicRouting | No rule found for dynamic routing | Configure appropriate dynamic routing rules to process the request correctly. |
| DP-4033 | ErrVerifyOTP | Failed to verify OTP code | Resend the OTP code to the payer or request a new one if the old one has expired. |
| DP-4034 | ErrWalletPayCredentialNotFound | No wallet payment method credentials found | Make sure the payer has set up their credentials correctly. |
| DP-4035 | ErrInstallmentPlan | Payment plans were not generated | Verify that customer data and system configurations are correct to enable payment plans. |
| DP-4100 | ErrMissingCVV | Failure to enter security code (CVV) | Asks the payer to provide the CVV code to complete the transaction. |
| DP-4101 | ErrInvalidCVV | The cvv is invalid | The CVV on the card is not correct, try a valid CVV. |
| DP-4102 | ErrInvalidInstallments | Invalid installment number | Review the available installment options and confirm that they match those offered by the provider. |
| DP-4103 | ErrInvalidTransactionAmount | Error with transaction amount | Confirm that the amount entered is correct and within the allowed limits. |
| DP-4104 | ErrInstallmentsNotSupported | The provider does not support installment plans | Review that the payment processor supports installments or use another payment processor |
| DP-4105 | ErrInstallmentsNotInstantiated | Error creating payment plans | Make sure the payment processor can create payment plans and that the necessary data is complete. |
| DP-4200 | ErrInternalServerErrorPSP | The processor returned an internal error | Retry the transaction or try another payment processor |
| DP-4210 | ErrGooglePayMessageExpired | Confirmation message has expired | Prompt the customer to restart the payment process. |
| DP-4211 | ErrGooglePayInvalidSignature | Invalid signature in the payment process | Make sure your customer and payment details are correct before processing again. |
| DP-4300 | ErrExpCard | Expiration date error | Validate the expiration date of the card |
| DP-4301 | ErrIDUser | Identification number/type error | Validate the identification number or type of the payer. |
| DP-4302 | ErrNameUser | Cardholder name error | Validate the cardholder’s name |
| DP-4303 | ErrNumberCard | Card number error | Validate the card number. |
| DP-4400 | ErrProcessing3DS | The 3DS windows cannot be started | Try again with another card or payment method |
| DP-4500 | ErrBankRejected | General decline by the issuer bank. | Try again with another card or payment method |
| DP-5001 | ErrNotImplemented | Payment method not configured | Validate the configuration of the payment method. |
| DP-5002 | ErrDB | The transaction could not be found or there was a problem with the Database connection | Validate the transaction ID and try again later. |
| DP-5003 | ErrDynamicRouting | Request to dynamic routing service failed | Review your routing configuration to ensure that the rules are correct and applicable. |
| DP-5004 | ErrFraudEvaluate | The fraud evaluation for the transaction has failed most likely due to missing parameters | Review the parameters requested for the processor |
| DP-5005 | ErrReview | Transaction review failure | Confirm that the transaction data is correct. |
| DP-5006 | ErrInitialGateway | Failed to start a new gateway | Ensure that the gateway configurations are correct and that it is available for use. |
| DP-6000 | ErrRequestAlreadyProcessed | The request is already processed or is in progress. | Try again with another request. |
| DP-6001 | ErrCannotUpdateTransaction | Cannot update transaction | Retry the request to update the transaction |
| DP-6002 | ErrCannotFindTransaction | The transaction was not found | Validate the transaction ID and retry. |
| DP-6003 | ErrUnknownPayment | The transaction may not have been approved | Make another transaction or try with another payment processor |
| DP-6004 | ErrCannotFindOrCreateTransaction | The transaction could not be found or created. | Make another transaction or try with another payment processor |
| DP-6005 | ErrUnknownRefund | The transaction has already been rejected or refunded | Please check the current status of the transaction before attempting a refund. |
| DP-6006 | ErrUnknownVoid | The transaction has already been rejected or voided | Please check the current status of the transaction before attempting a capture. |
| DP-6007 | ErrUnknownCapture | Failed to capture transaction | Please check the current status of the transaction before attempting a capture. |
| DP-6008 | ErrRefund | Refund transaction failure | Review the reasons for the refund failured returned by the processor. |
| DP-6009 | ErrCannotUpdatePartialRefund | Failure to update a partial refund | Make sure the partial refund parameters are correct and supported by your processor. |
| DP-6010 | ErrCannotFindPartialRefund | Failure to find a partial refund | Review the data and try again |
| DP-6011 | ErrOperationDisabled | The payment processor configuration does not allow the operation | Make another operation or try with another payment processor |
| DP-7011 | ErrWaitingOTP | The transaction is waiting for the OTP code. | Wait until you receive the OTP code to complete the transaction. |
| DP-7012 | ErrFailureOTP | The OTP code sent is not correct. | Review the code and try again or request a new code. |
| DP-7022 | ErrCardVault | The card number cannot be retrieved, is incorrect or is on the fraud list. | Try with another card or token. |
| DP-7023 | ErrSistecreditoPayment | The payment creation with SISCREDITO has failed | Review the information and make a new payment |
| DP-7100 | ErrWorkflowPurchase | Error when trying to create a transaction or tokenize a card due to missing parameters. | Review the required fields of the payload. |
| DP-7101 | ErrWorkflowAuthorize | Error performing an authorization transaction | Make sure the transaction details are correct and retry the transaction. |
| DP-7102 | ErrWorkflowCapture | Error performing a capture transaction | Verify that the funds have been authorized before attempting to capture them. |
| DP-7103 | ErrWorkflowVoid | Error when performing a void transaction | Confirm that the transaction is eligible to be voided and verify the processor details. |
| DP-7104 | ErrWorkflowRefund | Error when completing a refund transaction | Review that the refund parameters are correct. |
| DP-7105 | ErrWorkflowGetTransation | Error getting or reviewing a transaction | Make sure the transaction IDs are valid and the processor is available. |
| DP-7106 | ErrWorkflowBankList | Error when making a bank list request | Verify that the processor service is operational and retry the operation. |
| DP-7107 | ErrSettlementValidation | Cannot execute a capture, void or refund once the transaction is in settlement process. | Wait unitl the settlement process finishes or perform this type of transaction through the asynchronous v2 and automatically proceed to execute the desired transaction once the settlement is finished. |
| DP-7108 | ErrWorkflowInstallmentPlan | Error when making an installment plan request | Confirm that the payment processor supports installments and that the parameters are valid. |
| DP-7109 | ErrWorkflowCancelOrder | Failure when trying to cancel an order | Make sure the order is cancelable. |
| DP-8000 | ErrCannotGenerateQR | Cannot generate the QR code | Validate that the parameters to create the QR code are correct and complete. |
| DP-8001 | ErrFraudValidation | The processor returned a possible fraud error. | Review the parameters requested for the processor |
| DP-8002 | ErrFraudSystemConn | Payment method not found or connection error. | Review the payment method configuration in the Admin or try again later. |
| DP-9000 | ErrInsufficientFunds => ErrT1PagosRefund | There are no funds in the account to complete the operation | Validate your account funds and try again later. |
| DP-9001 | ErrMaxAttemps => ErrT1PagosVoid | The limit of attempts for the operation has been reached. | Validate your account and try again later. |
| DP-9999 | ErrUnknown | Generic error | Unknown error, please make a new request or contact support. |
| DPEC-000 | PaymentMessage000 | Content response failed when completing a transaction | Confirm that the transaction details are correct and that there are no problems communicating with the processor. |
Orders
| Error Code | Error type | Cause | Possible solution |
|---|---|---|---|
| EM-1000 | WithoutPaymentError | Failed to verify OTP code | Make sure the OTP code is valid and retry the operation. |
| EM-1001 | WithoutOrderIdError | Order ID is missing | Provide a valid order ID in the request and verify that it is not empty. |
| EM-1002 | OrderNotExist | The order does not exist | Review the order identifier and confirm that it is registered in the system. |
| EM-1003 | WithoutPaymentMethodError | Payment method is missing | Set up a valid payment method to complete the transaction. |
| EM-1004 | OrderWithoutPaymentMethod | The order does not have a payment method assigned | Make sure a payment method is associated with the order before proceeding. |
| EM-1005 | PaymentNotConfigured | Payment method is not configured | Verify that the payment method is enabled and correctly configured. |
| EM-1006 | OrderWithoutStoreCode | The order exists but there is not a store assigned to it | Provide the appropriate store code to continue the transaction. |
| EM-2000 | WithoutOrdenToken | Order token is missing when calculating the price | Provide a valid token and retry the operation. |
| EM-2001 | MissingParameters | Parameters are missing in the request to calculate the shipping | Review and complete the required parameters in the request before submitting it. |
| EM-3000 | CannotBeProcessed | Failed to canceled the transaction | Review the transaction data before trying again. |
| EM-4002 | OutOfStock | The requested item is not available in inventory | Review inventory levels and adjust product availability in the system. |
| EM-9998 | MerchantInternalError | Internal trade error | Internal error, please make a new request. |
| EM-9999 | MerchantUnknown | The merchant identifier is not present in the request | Make sure to include the merchant identifier in the request or review the structure of the data sent. |
Anti-fraud
| Error Code | Error type | Cause | Possible solution |
|---|---|---|---|
| FRD-7000 | FraudCodeScoreAndWorkflow | The fraud evaluation for the transaction has failed. Score was higher than the max score allowed and transaction stopped by the workflow | Retry the transaction or try another payment method |