Aprende como manejar los diferentes tipos de errores que se pueden presentar en las peticiones a nuestros endpoints
Estructura de errores
Las API retornará un objeto con dos atributos de respuesta para indicar cuál fue el error en la petición.
La respuesta esta conformada por:
- code que representa un Código genérico
- description que representa un mensaje descriptivo del error
{
"error": {
"code": "EMA-1000",
"description": "x-api-key"
},
"data": null
}
Cupones
| Código de error | Tipo de error | Descripción | Solución |
|---|---|---|---|
| EM-6000 | CuponNotFound | Cupón no encontrado | Verificar que el código del cupón este con el formato permitido y volver a intentar |
| EM-6001 | CuponNotApplicable | Cupón no es aplicable (vencido, no existe, etc.) | Verificar que el código del cupón sea valido, no este vencido y que exista |
| EM-6002 | CuponAlreadyUsed | Cupón ya utilizado | Verificar el limite de usos que tiene el cupón o si es un cupón único |
| EM-6003 | CuponAlreadyUsedInOrder | Cupón ya aplicado en la orden | Verificar si el cupón ya fue aplicado en la orden a través de obtener orden por token |
| EM-5000 | MerchantUnknown | Error desconocido |
Costos de envío
| Código de error | Tipo de error | Descripción | Solución |
|---|---|---|---|
| EM-4000 | WithoutCoverage | Ubicación de despacho fuera de zona de cobertura | Verificar la latitud y longitud del método de envio, y ver si se encuentra dentro de la zona de cobertura |
| EM-4001 | ClosedStore | Tienda cerrada | Verificar el horario de la tienda y comprobar que se encuentra abierta |
| EM-5000 | MerchantUnknown | Error desconocido |
Errores comunes en API
| Código de error | Tipo de error | Descripción | Solución |
|---|---|---|---|
| EMA-1000 | MissingHeaders | No se encontró el encabezado de la petición | Verificar que el encabezado se esté enviando de manera correcta en la petición |
| EMA-1001 | CannotGetMetadata | No se puede obtener la metadata. | Verificar si la metadata enviada en la petición tiene el formato correcto |
| EMA-1002 | PayloadError | Error en el payload. | Verificar si el payload o body que se está haciendo en la petición tiene el formato correcto |
| EMA-1003 | ShippingOptionNotAvailable | La opción de envio no se encuentra disponible | La opción de envió no se encuentra disponible| Verificar si la opción de envio es valida a las que tenemos disponibles: delivery,pickup |
| EMA-1004 | OrderAlreadyProcessed | La orden ya fue procesada | Generar otra orden, ya que la orden ya fue procesada |
| EMA-3000 | ConfigurationNotFound | No se encontró la configuración | No están configurados los endpoints de integración con el comercio |
| EMA-3001 | OrderNotFound | No se encontró la orden | Orden no registrada en el comercio, validar que esté correcta o que se encuentre dentro del comercio |
| EMA-3002 | DataBaseError | Error en la base de datos | Verificar la base de datos |
| EMA-4000 | RequestServiceError | Solicitud de error de servicio | Solicitud de error de servicio| Verificar si la solicitud al servicio es correcta |
| EMA-4001 | RequestServiceTimeout | Error en tiempo de espera de la solicitud de servicio | Tiempo de espera excedido, generar otra petición |
| EMA-5000 | Unauthorized | Sin autorización | Falta el X-API-Key en el encabezado de la petición |
| EMA-6000 | RefundError | Error de reembolso | Verificar si el body que se está haciendo en la petición tiene el formato correcto |
| EMA-6001 | VoidError | Error de anulación | Verificar si el body que se está haciendo en la petición tiene el formato correcto |
| EMA-6007 | CannotGetWebhook | No se puede obtener la configuración del webhook | Verificar si el body que se está haciendo en la petición tiene el formato correct |
| EMA-6010 | ErrorFromMerchant | Error proveniente de la API del merchant | Verificar si el body que se está haciendo en la petición tiene el formato correct |
| EMA-6011 | CannotUpdateOrder | No se puede actualizar la orden | Verificar si el body que se está haciendo en la petición tiene el formato correct |
| EMA-6019 | OrderExpired | Esta orden ya está en estado expired y por ende no se puede intentar pagar. Este error es arrojado al momento de intentar pagar una orden expirada. | Debes crear una nueva orden. |
| EMA-6020 | CannotExpireOrder | No se puede expirar esta orden pues o ya está expirada o tiene un intento de pago asociado. Casos especiales: PIX: se permite expirar una orden cuando esta no tiene ningún intento de pago asociado o el intento de pago asociado esta en pending. | Debes crear una nueva orden. |
Enlaces de pago
| Código de error | Mensaje | Descripción | Solución |
|---|---|---|---|
| EMA-6021 | CannotCreatePaymentLinkTemplate | Ocurrió un error al intentar crear el template del payment link. | Verifica campos que se envían en la solicitud de payment link requeridos en la creación. |
| EMA-6022 | CannotGetPaymentLinkTemplate | No se pudo encontrar el template del Enlace de pago solicitado. | Verifica el ID de payment link solicitado. |
| EMA-6023 | CannotUpdatePaymentLinkTemplate | Hubo un error al intentar actualizar el template del Enlace de pago. | Verifica campos obligatorios solicitados para actualizar link de pago. |
| EMA-6024 | InvalidStatusTransitionPaymentLinkTemplate | La transición de estado solicitada no es válida o el estado no permite modificaciones. | El estado actual no permite modificaciones. Verifica que el estado sea elegible para cambio o modificación antes de intentar una transición. |
| EMA-6025 | PaymentLinkTemplateExpired | El template del Enlace de pago ha expirado y ya no puede ser utilizado. | Genera un nuevo link de pago si se necesita continuar con la operación o edita la fecha de expiración del enlace de pago actual. |
| EMA-6026 | PaymentLinkTemplateLimitExceeded | Se ha superado el límite máximo de usos permitidos para el Enlace de pago. | Crea un nuevo link de pago o incrementa el límite de redenciones si es posible. |
| EMA-6027 | PaymentLinkTemplateCompleted | El template del Enlace de pago ya ha sido completado. | No se requiere acción adicional. Si se necesita un nuevo pago, genera un nuevo link. |
| EMA-6028 | PaymentLinkTemplateDisabled | El template del Enlace de pago está desactivado y no puede ser utilizado. | Verifica la configuración del link y, si es necesario, reactívalo o crea uno nuevo. |
| EMA-6029 | PaymentLinkTemplateCanceled | El template del Enlace de pago ha sido cancelado, por lo que no es posible continuar con la operación. | Crea un nuevo link de pago si se requiere una nueva transacción. |
Checkout
| Código de error | Tipo de error | Descripción | Solución |
|---|---|---|---|
| CHECKOUT-1000 | CheckoutNotReady | Checkout no esta listo para iniciar | Verificar la configuración del checkout |
| CHECKOUT-1001 | CheckoutNotReadyForShipping | Checkout no esta preparado para el envio | Verificar la configuración de endpoints de métodos y tarifas de envío |
| CHECKOUT-1002 | CheckoutNotReadyForNotify | Checkout no esta preparado para notificar | Verificar endpoint de notificación de ordenes |
Payments
| Código de error | Tipo de error | Descripción | Solución |
|---|---|---|---|
| DP-3000 | ErrPayload | Error en el payload enviado en la petición o esta vacío | Verificar el payload que se esta enviando, validar si los campos enviados son los requeridos o si esta vacío. |
| DP-3001 | ErrCannotParseData | No se puede verificar la data enviada | Validar el payload de data que se envía en la solicitud es correcto |
| DP-3002 | ErrRequestServiceError | Error en la petición que se realizo | Volver a realizar una petición con los datos correctos |
| DP-3003 | ErrAmountRequest | Error en el monto enviado | Validar que el campo de los montos coincidan o no vayan nulos en la petición |
| DP-4000 | ErrMissingHeaders | No se encontró el encabezado de la petición | Verificar que el encabezado se esté enviando de manera correcta en la petición. |
| DP-4001 | ErrUnauthorized | Sin autorización | Falta el X-API-Key en el encabezado de la petición. |
| DP-4002 | ErrCardTokenForbidden | Tarjeta prohibida | La tarjeta se encuentra en la lista negra de fraudes. |
| DP-4003 | ErrStoreCodeValidation | No se encontró el código de la tienda | Revisar el código de la tienda que se esta enviando dentro de la petición. |
| DP-4004 | ErrValidation | Revisar el payload enviado | Validar que el payload enviado se encuentre con la estructura requerida. |
| DP-4005 | ErrMerchantIDValidation | No se encontró el código del comercio | Verificar si el código de la tienda es el correcto o si se esta enviando vacío. |
| DP-4006 | ErrUserValidation | Usuario es requerido | Se debe enviar la información del usuario al crear la orden. |
| DP-4007 | ErrParseUuid | No se puede obtener el token de orden | Revisar si el token de la orden se esta enviando correctamente. |
| DP-4008 | ErrCardNotFound | Tarjeta no encontrada | El numero de la tarjeta no es correcto, intentar con una nueva tarjeta. En caso se esté usando card_id este error significa que el card_idno hace parte o no está asociado al usuario que se está utilizando para crear el /purchase |
| DP-4009 | ErrProcessorNotFound | No se ha encontrado el procesador para la tarjeta de crédito | Revisar en el Admin si el método de pago esta configurado. |
| Dp-4100 | ErrMissingCVV | No se encontró el cvv | Revisar que se este enviando el cvv dentro de la petición. |
| DP-4101 | ErrInvalidCVV | El cvv es inválido | El cvv de la tarjeta no es correcto, intentar con un cvv válido. |
| DP-4200 | ErrTransactionProcessor | Error con la comunicación del procesador | Volver a intentar la transacción o intentar con otro procesador de pago |
| DP-4300 | ErrExpCard | Error en la fecha de expiración | Solicitar que se ingrese la información correcta de la tarjeta |
| DP-4301 | ErrIDUser | Error en el número/tipo de identificación | Solicitar que se ingrese la información correcta de la cédula de identificación |
| DP-4302 | ErrNameUser | Error en el nombre del tarjetahabiente | Solicitar que se ingrese la información correcta de la tarjeta |
| DP-4303 | ErrNumberCard | Error en el numero de la tarjeta | Solicitar que se ingrese la información correcta de la tarjeta |
| DP-4400 | ErrProcessing3DS | Error en el procesamiento con 3DS | Intentar de nuevo con otra tarjeta o medio de pago |
| DP-4500 | ErrBankRejected | Declinación general por el banco emisor | Intentar de nuevo con otra tarjeta o medio de pago |
| DP-5001 | ErrNotImplemented | Método de pago no configurado | Revisar en el Admin si el método de pago esta configurado. |
| DP-5002 | ErrDB | Transacción no encontrada | La transacción no pudo ser encontrada en la BD, revisar la información para confirmar que se este enviando correctamente. |
| DP-6000 | ErrRequestAlreadyProcessed | Solicitud ya procesada o en curso | La solicitud ya se encuentra procesada o esta en curso, enviar otra solicitud. |
| DP-6001 | ErrCannotUpdateTransaction | No se puede actualizar la transacción | Volver a enviar otra solicitud para actualizar la transacción. |
| DP-6002 | ErrCannotFindTransaction | No se encuentra la transacción | Revisar si la transacción se esta enviando de manera correcta. |
| DP-6003 | ErrUnknownPayment | La transacción podría no haber sido aprobada | Realizar otra transacción o probar con otro procesador de pago |
| DP-6004 | ErrCannotFindOrCreateTransaction | No se puede encontrar o crear una transacción | Hacer otra transacción o intentar con otro procesador de pago |
| DP-6011 | ErrOperationDisabled | El procesador no soporta la operación. Ejemplo: reembolsos parciales no disponibles para Paymentez | Realizar otro tipo de operación |
| DP-7011 | ErrWaitingOTP | Esperando código OTP | Esperar al envio del código OTP requerido para completar la transacción |
| DP-7012 | ErrFailureOTP | Fallo OTP | El código OTP ingresado no es correcto, revisar o solicitar un nuevo código |
| DP-7022 | ErrCardVault | No se puede obtener la tarjeta | El número de la tarjeta es incorrecto o se encuentra en la lista de fraudes, intentar con otra tarjeta. |
| DP-7023 | ErrSistecreditoPayment | Error en la creación del pago | Revisar la información enviada para realizar el pago |
| DP-7100 | ErrDeferPayment | Error en la petición de diferir cobro | Revisar la configuración del método de pago |
| DP-7107 | ErrSettlementProcessingOperation | Error ejecutando una captura, void y/o refund, cuando la transacción está siendo liquidada | Esperar hasta que se termine el proceso de liquidación o realizar la operación a través de la versión 2 del API |
| DP-8000 | ErrCannotGenerateQR | No se puede generar el código QR | Validar si el contenido que ira dentro del QR es correcto. |
| DP-8001 | ErrFraudValidation | La transacción podría no haber sido aprobada | Realizar otra transacción debido a que fue rechazada por nuestro sistema anti fraude |
| DP-8002 | ErrFraudSystemConn | Método de pago no encontrado o error de conexión | Revisar el método de pago que se solicito se encuentra dentro del Admin |
| DP-9000 | ErrInsufficientFunds | No se cuenta con los fondos en la cuenta para poder finalizar la orden | Intentar de nuevo con otra tarjeta o medio de pago |
| DP-9001 | ErrMaxAttemps | Se ha alcanzado el limite de intentos/saldo | Intentar de nuevo con otra tarjeta o medio de pago |
| DP-9999 | ErrUnknown | Unknown error | Error desconocido, vuelva a realizar una nueva solicitud |