Códigos de error

Aprende sobre errores comunes y cómo resolverlos

Aprende cómo manejar los diferentes tipos de mensajes de error recibidos durante las transacciones para cada medio de pago.

¿Qué tipo de códigos de respuesta retorna Kushki?

Kushki retornará dos códigos diferentes de respuesta para indicar el éxito o fallo de las transacciones: processorError y code. El campo code retorna mensajes genéricos. Por su parte, el campo processorError indica que la transacción ha pasado a través del procesador y probablemente ha sido mapeado por Kushki para darte una idea específica de porqué tu transacción no se pudo completar.

Códigos retornados por Kushki para pagos únicos con tarjeta

La API de Kushki realizará validaciones antes de enviar la transacción hacia los procesadores. Si este es el caso, el campo processorError no aparecerá en la respuesta y solo verás el campo code . El siguiente es un ejemplo de un mensaje retornado por el API de Kushki:

{"message": "ID de comercio o credencial no válido",
"code": "K004" }

A continuación te presentamos los códigos de error genéricos retornados en el campo code.

codemessage¿Qué hacer?
006Transacción abandonada-
017Tarjeta no válidaIntentar con otra tarjeta
201ID de comercio no válidoRevisar las credenciales enviadas y reintentar
228Procesador inalcanzableNo fue posible establecer comunicación con el procesador
228Procesador inalcanzableNo fue posible establecer comunicación con el procesador
577El token de la transacción no es válidoEnviar nuevamente los datos para obtener un nuevo token
621Transaccion cancelada por el usuario-
622Tiempo se sesión expiradoIntentar nuevamente la transacción
703El monto de la transacción es requeridoAsegurarse de enviar el monto y reuintentar
K001El cuerpo de la petición es inválidoRevisar el body de la petición
K002Ha ocurrido un error inesperadoReintentar la transacción, en caso de que el error persista comunícate con el equipo de soporte de Kushki para revisar el caso.
K003Procesador no existeComunícate con el equipo de soporte de Kushki para revisar el caso
K004Id de comercio no válidoVerificar el public merchant ID o el private merchant ID y reintentar
K005Id de procesador no válidoComunícate con el equipo de soporte de Kushki para revisar el caso
K007Tarjeta bloqueada por el emisorInternar con otra tarjeta
K008Token incorrectoCompletar nuevamente los datos y reintentar
K009Review SSM variablesCompletar nuevamente los datos y reintentar
K011Bin no válidoInterna con otra tarjeta
K012Monto de captura inválidoVerificar el monto a capturar y reintentar
K013Transación tokenizada como diferidoVerificar que la información de cuotas haya sido enviada en la solicitud de cobro
K015CVV2_REJECTED_TRANSACTIONVerificar el CVV y reintentar
K016Método no implementadoComunícate con el equipo de soporte de Kushki para revisar el caso
K020ERROR_REJECTED_TRANSACTIONReintentar la transacción, en caso de que el error persista comunícate con el equipo de soporte de Kushki para revisar el caso
K021ERROR_REJECTED_TRANSACTIONReintentar la transacción, en caso de que el error persista comunícate con el equipo de soporte de Kushki para revisar el caso
K023Monto del void superior al del saleEste mensaje se presenta cuando se trata de hacer un void parcial pero el monto es superior al monto de la venta
K025Tarjeta inválidaIntentar con otra tarjeta
K026Processor DeclinedComunícate con el equipo de soporte de Kushki para revisar el caso
K027La operación cayó en timeout, por favor inténtelo de nuevoIntenta nuevamente la transacción
K028El comercio no tiene habilitado la opción de diferidos-
K029Bin de tarjeta inválidoInterna con otra tarjeta
K030Procesador inalcanzableIntenta nuevamente la transacción
K038No se puede realizar un void parcial sin especificar el valor a sustraerEspecificar el objecto amount
K039La suma de los valores de la propiedad amount debe ser mayor a 0Se debe enviar un monto mayor a 0 en la propiedad amount.
K040El ID de comercio no corresponde a la credencial enviadaSe debe enviar un monto mayor a 0 en la propiedad amount.
K041Operación no permitidaComunícate con el equipo de soporte de Kushki para revisar el caso
K042El código de moneda es diferente al de la transacción inicial.Este mensaje se presenta cuando se envía un código de moneda diferente al de la transacción inicial. Envía el código de moneda correcto.
K047Ha ocurrido un error inesperadoIntenta nuevamente la transacción
K048Token expiradoEnvía los datos e intenta nuevamente la transacción
K049Token utilizado anteriormenteEnvía los datos e intenta nuevamente la transacción
K220Monto de la transacción es diferente al monto de la venta inicialEl monto enviando en el token debe ser igual al de la compra. Será necesario asegurarse que el monto a pagar sea el correcto.
K322Transacción rechazadaLa transacción fue rechazada por una regla de seguridad de Kushki. Comunícate con el equipo de soporte de Kushki para revisar el caso

Códigos de error autenticación OTP

Las transacciones declinadas por reglas de seguridad en Kushki tendrán un código K322 como respuesta genérica. En caso de que falle la autenticación OTP, en tu Consola podrás consultar en el módulo de transacciones la causal de rechazo al abrir el detalle de la transacción el cual tendrá un subcódigo de rechazo K326.

Sigue las instrucciones presentadas a continuación para consultar el detalle de la autenticación OTP:

  1. Ingresa a tu consola con un Usuario de Lectura o un Usuario Maestro.
  2. Dirígete al módulo de Transacciones>>Cobros.
  3. Utiliza los filtros disponibles para buscar la transacción deseada.
  4. Haz clic sobre la transacción. Se abrirá la ventana Detalle de la Transacción.
  5. En la parte inferior del detalle aparecerá la sección Datos de la autenticación. Desde allí podrás consultar el motivo de la declinación.

El siguiente GIF te guiará a través del proceso de revisión del detalle de la autenticación:

Códigos de error OTP

Código de error de autenticaciónDescripción
K326Autenticación fallida - Clave incorrecta
K326Autenticación fallida - Intentos excedidos
K326Autenticación fallida - Abandono
K326Autenticación fallida - Error de autenticación

Códigos de error cuando la transacción viaja al procesador

A continuación te presentamos los códigos de error retornados en el campo processorError, de forma que puedas usar estos para mapear los mensajes de tu aplicación.

Las columnas processorError y message te mostrarán el código de error y mensaje enviado desde Kushki. En la columna ¿Qué hacer? te damos una explicación más detallada de las causas y el posible procedimiento a seguir.

processorErrormessage¿Qué hacer?
501Transacción rechazada. Póngase en contacto con el emisor de su tarjetaEl tarjetahabiente deberá ponerse en contacto con el emisor de su tarjeta para conocer las razones por las cuales se rechazó la transacción
503El número de comercio no está registradoEl número de terminal o código del comercio no está registrado o habilitado en el procesador. Comunícate con el equipo de soporte de Kushki para revisar el caso.
504La tarjeta ingresada ha sido reportada.El tarjetahabiente deberá usar una tarjeta diferente para procesar la transacción y ponerse en contacto con el emisor de su tarjeta para revisar el caso.
505La transacción fue declinada por el procesador o emisor.El tarjetahabiente deberá esperar un par de minutos y reintentar, de lo contrario, usar una tarjeta alternativa.
512Transacción no permitida por el emisor.La Transacción no está permitida por el procesador o el emisor. El tarjetahabiente deberá usar una tarjeta alternativa.
513El monto que ingresó contiene una sintaxis no válidaEs necesario verificar el monto ingresado y reintentar. Por ejemplo, es posible que se hayan ingresado caracteres no permitidos en el monto, como , en lugar de . para separar decimales.
514El número de tarjeta ingresado no es válidoEl tarjetahabiente deberá verificar que el número de tarjeta haya sido ingresado correctamente y reintentar.
515El emisor no puede autorizar esta transacciónEl procesador o franquicia rechazó el BIN enviado. El tarjetahabiente deberá usar otra tarjeta.
518Has ingresado una tarjeta vencidaLa tarjeta se encuentra caducada o la fecha es incorrecta. El tarjetahabiente deberá revisar que la fecha esté correcta o intentar con otra tarjeta.
519Se produjo un error al procesar la operación. Inténtalo de nuevoEl tarjetahabiente deberá reintentar la transacción.
520El nombre del titular de la tarjeta ingresado no es correctoIngresar nuevamente el nombre del tarjetahabiente y reintentar.
521El apellido del titular de la tarjeta ingresado no es correctoIngresar nuevamente el apellido del tarjetahabiente y reintentar.
522El correo electrónico que ha ingresado no es válido.Ingresar nuevamente el correo electrónico del tarjetahabiente y reintentar.
523El número de la dirección IP es incorrecto.Verificar que la transacción se esté efectuando desde una dirección IP válida.
524El número de identificación que ha ingresado es incorrecto.Ingresar nuevamente el tipo y número de identificación del tarjetahabiente y reintentar.
525La información encriptada no es válidaEl proceso de encriptación de la información no pudo completarse correctamente. Comunícate con el equipo de soporte de Kushki para revisar el caso.
526El comercio no tiene permiso para procesar una transacciónSe debe a una restricción del procesador al comercio. Comunícate con el equipo de soporte de Kushki para revisar el caso.
527El monto enviado no puede ser ceroEl monto de esta transacción no puede ser cero. Se debe ingresar un monto diferente y reintentar.
528Monto de la transacción es diferente al monto de la venta inicialEl monto enviando en el token debe ser igual al de la compra. Será necesario asegurarse que el monto a pagar sea el correcto.
529No ha sido posible encontrar la transacciónAl realizar el reverso o anulación no fue posible encontrar el mensaje original. Comunícate con el equipo de soporte de Kushki para revisar el caso.
530Transacción rechazada por error de formatoAl momento de realizar la transacción se presentó un error en el formato de la misma. Comunícate con el equipo de soporte de Kushki para revisar el caso.
541Esta tarjeta ha sido reportada como perdidaEl tarjetahabiente deberá usar una tarjeta diferente para procesar la transacción y ponerse en contacto con el emisor de su tarjeta para revisar el caso.
543Esta tarjeta ha sido reportada como robadaEl tarjetahabiente deberá usar una tarjeta diferente para procesar la transacción y ponerse en contacto con el emisor de su tarjeta para revisar el caso.
551No hay fondos suficientes para completar la operación.El tarjetahabiente deberá usar una tarjeta diferente para procesar la transacción ya que la tarjeta ingresada no cuenta con los fondos suficientes para procesar la transacción.
552El tipo de cuenta ingresado no es válidoEl tarjetahabiente deberá verificar el tipo de cuenta seleccionada e internar nuevamente.
553La tarjeta no es compatibleLa marca de la tarjeta ingresada no es compatible para poder efectuar la autorización. El tarjetahabiente deberá usar una tarjeta diferente para procesar la transacción.
554El tipo de moneda no es válidoEl procesador o emisor no acepta transacciones en la moneda seleccionada. Comunícate con el equipo de soporte de Kushki para revisar el caso.
555La solicitud enviada no es válidaHa existido una novedad en la solicitud de la transacción que se ha realizado. Comunícate con el equipo de soporte de Kushki para revisar el caso.
556La transacción se encuentra anuladaLa transacción que se está intentando anular o reversar ya fue anulada anteriormente
557El emisor no puede autorizar esta transacciónPor restricciones del emisor no es posible autorizar la Transacción. El tarjetahabiente deberá cambiar de tarjeta o medio de pago y ponerse en contacto con el emisor de su tarjeta para revisar el caso.
558Transacción no permitida al comercioPor restricciones del procesador no es posible autorizar la Transacción al comercio. Comunícate con el equipo de soporte de Kushki para revisar el caso.
559La transacción ha sido considerada como una sospecha de fraudeLa transacción que se ha realizado fue declinada por el procesador o emisor por sospecha de fraude.
560El monto ingresado es menor o mayor de lo permitidoEl monto enviado en la transacción es menor o mayor a los límites que han sido establecidos. El tarjetahabiente deberá verificar el monto de la transacción y reintentar.
561Se ha excedido el límite diario de transaccionesEl tarjetahabiente ha superado el límite de actividad en cantidad o monto de transacciones diarias
562Tarjeta restringida por el emisorEl emisor ha declinado la transacción porque aplicó restricciones al tarjetahabiente. El tarjetahabiente deberá ponerse en contacto con el emisor de su tarjeta para revisar el caso.
563Operación rechazada por violación de seguridadEl emisor o procesador declinó la transacción porque existe una violación de seguridad.
564El token ingresado no es válido o ha expiradoEl token que se está usando no posee un formato válido, no existe o ya fue usado en una transacción
565La transacción fue declinada por reglas de seguridadLa transacciones está siendo declinada por reglas de seguridad configuradas a la tarjeta o al comercio
566El token es inváalido , o ya fue usado en otra transacciónEl token que se está usando no posee un formato válido, no existe o ya fue usado en una transacción. Comunícate con el equipo de soporte de Kushki para revisar el caso.
567El monto de la transacción es requeridoEs obligatorio enviar un valor en el campo “amount”.
568El número de ticket de la transacción no es válidoIngresa nuevamente el número de ticket, si el error persiste, comunícate con el equipo de soporte de Kushki para revisar el caso.
579La fecha de vencimiento ingresada es incorrectaEl tarjetahabiente deberá ingresar nuevamente la fecha de vencimiento e intentar otra vez.
580El diferido enviado no es correctoEl tipo de diferido o formato del diferido que se está empleando no es el correcto. Comunícate con el equipo de soporte de Kushki para revisar el caso.
581Las credenciales no son correctasVerífica las credenciales enviadas e íntentalo de nuevo
582El número de seguridad (cvv2) ingresado no es correctoEl tarjetahabiente deberá ingresar nuevamente el código de seguridad y reintentar la transacción.
583La operación ya se canceló o se alcanzó el tiempo máximo para revertirNo es posible cancelar o revertir la transacción porque ya fue cancelada, no se encontró la transacción original , o se ha cumplido el tiempo máximo permitido para poder reversarla. Comunícate con el equipo de soporte de Kushki para revisar el caso.
591Transacción no autorizada. Emisor inoperativoEsperar un par de minutos y reintentar, de lo contrario, usar una tarjeta alternativa.
594La transacción rechazada parece ser una operación duplicadaLa transacción fue declinada porque existe una coincidencia con otra transacción realizada anteriormente. Comúnmente porque se está enviando el mismo número de referencia.
596El emisor ha tenido un problema al autorizar la transacción.El tarjetahabiente deberá esperar un par de minutos y reintentar, de lo contrario, usar una tarjeta alternativa o comunicarse con el emisor de la tarjeta para verificar.

Códigos retornados por Kushki para cargos recurrentes con tarjeta

La API de Kushki realizará validaciones antes de enviar la transacción hacia los procesadores. Si este es el caso, el campo processorError no aparecerá en la respuesta y solo verás el campo code . El siguiente es un ejemplo de un mensaje retornado por el API de Kushki:

{"message": "Comercio deshabilitado",
"code": "K026" }

A continuación te presentamos los códigos de error genéricos retornados en el campo code.

codemessage¿Qué hacer?
K001El cuerpo de la petición es inválidoRevisar el body de la petición
K003Error en la respuesta del gatewayReintentar, en caso de que el error persista, comunícate con el equipo de soporte de Kushki para revisar el caso
K004Id de comercio no válidoVerificar el public merchant ID o el private merchant ID y reintentar
K007Tarjeta bloqueada por el emisorInternar con otra tarjeta
K008Token incorrectoCompletar nuevamente los datos y reintentar
K010Comercio no habilitado para suscripcionesComunícate con el equipo de soporte de Kushki para revisar el caso
K011Fecha de inicio inválidaRevisar la fecha de inicio enviada en la variable startDate
K012ID de suscripción no válidaVerificar el monto a capturar y reintentar
K013Fecha final inválidaRevisar la fecha enviada en la variable endDate
K014Monto de captura inválidoVerificar el monto de la captura y reintentar
K015Transacción no permitida sin ccv2Verificar el CVV y reintentar
K016No es posible actualizar la subscripciónVerificar la información enviada y reintentar
K020ERROR_REJECTED_TRANSACTIONReintentar la transacción, en caso de que el error persista comunícate con el equipo de soporte de Kushki para revisar el caso
K021ERROR_REJECTED_TRANSACTIONReintentar la transacción, en caso de que el error persista comunícate con el equipo de soporte de Kushki para revisar el caso
K022Token utilizado anteriormenteEnviar la información nuevamente y reintentar
K023Monto del void superior al del saleEste mensaje se presenta cuando se trata de hacer un void parcial pero el monto es superior al monto de la venta
K024El valor del monto debe ser mayor a ceroVerificar el monto enviado y reintentar
K025Tarjeta inválidaIntentar con otra tarjeta
K026Comercio deshabilitadoComunícate con el equipo de soporte de Kushki para revisar el caso
K027No se pudo completar la transacciónIntentar nuevamente la transacción
K028Processor DeclinedComunícate con el equipo de soporte de Kushki para revisar el caso
K029Los datos de tarjeta no coiciden en la subscripción y su confirmaciónRevisar los datos enviados y reintentar
K031No existe la subscripción webpay a confirmarRevisar el ID de suscripción enviado y reintentar
K032La subscripción webpay ha sido confirmada anteriormente-
K034No existen procesadoresComunícate con el equipo de soporte de Kushki para revisar el caso
K035Procesador no disponibleReintenta nuevamente. Si el error persiste, comunícate con el equipo de soporte de Kushki para revisar el caso
K036Error de integración con un terceroComunícate con el equipo de soporte de Kushki para revisar el caso
K037Subscripción no encontradaRevisa el ID de suscripción enviado e inténtalo de nuevo
K038No se puede realizar un void parcial sin especificar el valor a sustraerEspecificar el objecto amount
K039La suma de los valores de la propiedad amount debe ser mayor a 0Se debe enviar un monto mayor a 0 en la propiedad amount.
K040El ID de comercio no corresponde a la credencial enviadaSe debe enviar un monto mayor a 0 en la propiedad amount.
K041Operación no permitidaComunícate con el equipo de soporte de Kushki para revisar el caso
K042El código de moneda es diferente al de la transacción inicial.Este mensaje se presenta cuando se envía un código de moneda diferente al de la transacción inicial. Envía el código de moneda correcto.
K043Transacción de preautorización no corresponde a la suscripciónRevisa la información enviada e inténtalo nuevamente
K044El bin ingresado no soporta este método de pagoIntenta con otra tarjeta
K045Transacción de captura realizada anteriormenteNo es posible realizar la captura nuevamente
K046La operación cayó en timeout, por favor inténtelo de nuevoReintenta la transacción
K047Ha ocurrido un error inesperadoReintenta la transacción
K048Procesador no soporta el actual métodoComunícate con el equipo de soporte de Kushki para revisar el caso
K049Tarjeta expiradaIntenta con otra tarjet
K050Este token ya no es válidoRevisar los datos enviados y reintentar
K051El comercio no tiene habilitado la opción de diferidosComunícate con el equipo de soporte de Kushki para revisar el caso
K052ERROR_REJECTED_TRANSACTIONReintentar la transacción, en caso de que el error persista comunícate con el equipo de soporte de Kushki para revisar el caso
K027La operación cayó en timeout, por favor inténtelo de nuevoIntentar nuevamente la transacción

Códigos retornados por Kushki para pagos en efectivo

La API de Kushki realizará validaciones antes de enviar la transacción hacia los procesadores. Si este es el caso, el campo processorError no aparecerá en la respuesta y solo verás el campo code . El siguiente es un ejemplo de un mensaje retornado por el API de Kushki:

{"message": "ID de comercio o credencial no válido",
"code": "K004" }

A continuación te presentamos los códigos de error genéricos retornados en el campo code.

codemessage¿Qué hacer?
K001El cuerpo de la petición es inválidoRevisar el body de la petición
K002Ha ocurrido un error inesperadoReintentar la transacción, en caso de que el error persista comunícate con el equipo de soporte de Kushki para revisar el caso.
K003Token inválidoCompletar nuevamente los datos y reintentar
K004Id de comercio no válidoVerificar el public merchant ID o el private merchant ID y reintentar
K005Id de transacción no válidoCompletar nuevamente los datos y reintentar
K006Monto de la transacción inválidoVerificar el monto a capturar y reintentar
K007El pin enviado no existeVerificar el pin y reintentar
K008La transacción está en un estado no válidoVerificar que la transacción no haya sido pagada previamente o anulada
K009El pin ya se encuentra en estado de pagadoYa se ha realizado el pago previamente
K010Error de integración con un terceroComunícate con el equipo de soporte de Kushki para revisar el caso
K011Error no hay adjuntos en el correoInternar con otra tarjeta
K012Estatus de transacción invalidoVerificar el monto a capturar y reintentar
K017La fecha de expiración no es válidaComunícate con el equipo de soporte de Kushki para revisar el caso
K018La transacción no existe o ha sido eliminadaComunícate con el equipo de soporte de Kushki para revisar el caso
K019El comercio no tiene businessIdComunícate con el equipo de soporte de Kushki para revisar el caso
K021No se encotraron registros para los criterios de búsqueda.Reintentar la transacción, en caso de que el error persista comunícate con el equipo de soporte de Kushki para revisar el caso
K022No se puede eliminar esta transacciónComunícate con el equipo de soporte de Kushki para revisar el caso
K023No es posible actualizar la transacciónEste mensaje se presenta cuando se trata de hacer un void parcial pero el monto es superior al monto de la venta
K025El comercio no dispone de procesadoresComunícate con el equipo de soporte de Kushki para revisar el caso
K026La validación de firma de la petición fallóIntentar nuevamente la transacción
K032No existen redes de pagoComunícate con el equipo de soporte de Kushki para revisar el caso
K033Transacción previamente anuladaLa transacción ya fue anulada
K034Error de validación Stone webhook-
K035El pin generado por el procesador duplicadoEl pin está duplicado, intenta generar un nuevo pin
K036La transacción ya no puede ser reversadaLa transacción se encuentra en un estado en el que no se puede reversar
K037La operación cayó en timeout, por favor inténtelo de nuevoIntenta nuevamente
K038El procesador no existeComunícate con el equipo de soporte de Kushki para revisar el caso
K040El ID de comercio no corresponde a la credencial enviadaSe debe enviar un monto mayor a 0 en la propiedad amount.
K041El comercio no tiene procesadores disponiblesComunícate con el equipo de soporte de Kushki para revisar el caso

Códigos de estado HTTP

Kushki podrá retornar diferentes códigos de estado HTTP dependiendo de las solicitudes realizadas. Existen cinco categorías de respuestas estándar, descritas en la siguiente imagen:

Códigos de estado HTTP

A continuación te presentamos los códigos de estado HTTP más comunes, su mensaje estándar asociado, así como una descripción más detallada de la respuesta.

CódigoMensajeDetalle
200OKEl proceso fue exitoso. Todo funcionó de la manera que se esperaba, según el método HTTP
400Bad RequestEl servidor no puede interpretar la solicitud (sintaxis incorrecta, tamaño demasiado grande, faltan parámetros)
401Authorization RequiredSe deben autenticar las credenciales, o bien, la autenticación ha fallado
403ForbiddenNo se cuenta con los permisos necesarios para realizar esa acción
404Not FoundRecurso o página no encontrada
409ConflictLa solicitud no puede ser procesada por un conflicto con el recurso (por ejemplo, múltiples actualizaciones simultáneas)
410GoneEl recurso solicitado ha sido borrado del servidor, y ya no está ni estará disponible
429Too Many RequestsSe han enviado demasiadas solicitudes en un tiempo determinado
430Request Header Fields Too LargeCódigo no oficial, aplica solo para Shopify. Similar al código 429
500Internal Server ErrorOcurrió un error inesperado del lado del servidor
502Bad GatewayEl servidor (actuando como proxy o gateway) recibió una respuesta inválida de otro servidor
503Service Temporarily UnavailableEl servidor no está disponible (comúnmente es porque se encuentra en mantenimiento, o porque está sobrecargado)
504Gateway TimeoutEl servidor (actuando como proxy o gateway) no ha recibido una respuesta del otro servidor a tiempo