Catálogo Unificado de Errores — Kushki ONE Connect

09 septiembre 2026

Kushki ONE Connect devuelve un payload JSON estructurado ante cualquier fallo, sin importar si el problema se originó en la terminal, en una validación, en la autenticación o en el adquirente. Eso te permite construir integraciones robustas, automatizar flujos de recuperación y dejar de depender exclusivamente de los códigos de estado HTTP.

Este manual es tu herramienta de diagnóstico: la estructura del modelo de datos, los catálogos por categoría, cómo mapeamos los rechazos de terceros y una guía rápida para resolver los casos frecuentes.

1. Modelos de errores

Existen dos envolturas de error. Cuál recibes depende de si el fallo llega en una respuesta HTTP o en un evento asíncrono.

1.1 Respuestas HTTP: LinkFailure

Toda respuesta de error comparte esta estructura. Evalúa primero el campo type para clasificar la fuente del fallo y luego consulta el code correspondiente.

En los endpoints de pago el status HTTP es siempre 200, pase lo que pase: confirma que la terminal procesó tu petición, no que la operación haya salido bien. Evalúa siempre el cuerpo. Los endpoints de impresión son la excepción y devuelven códigos reales — 404 si el job no existe, 409 mientras la cola está ocupada.

Los cinco campos de arriba están en la raíz del cuerpo. Las dos envolturas que devolvían las versiones viejas, {"success": false, "data": {…}} y {"failure": {…}}, ya no existen. Y object.terminal_id puede llegar vacío en TER-003 — no dependas de él.

{
  "type": "PARAMETER",
  "code": "PAR-003",
  "param": "amount",
  "message": "Amount must be a value greater than 0",
  "object": {
    "client_transaction_id": "1018282",
    "terminal_id": "172653",
    "serial_number": "PJ715652"
  }
}

1.2 Eventos asíncronos: failure_reason

Cuando integras por el modo asíncrono, los fallos no llegan en una respuesta HTTP sino dentro del evento del webhook, en el objeto failure_reason.

{
  "status": "TERMINAL_REJECTED",
  "previous_status": "CARD_PRESENTED",
  "client_transaction_id": "c5a3f3be-9d6f-4d39-8af5-58dbb589af79",
  "failure_reason": {
    "type": "TERMINAL",
    "code": "TER-172",
    "message": "The maximum operation time was exceeded."
  }
}

Cuándo viene param y cuándo no

param no es un campo opcional que a veces falta. Se omite deliberadamente cuando el error no lo causó un campo de tu request. La regla en una línea: param aparece solo cuando el error es atribuible a un campo del request.

Sin esta regla un integrador lee el catálogo, ve param entre los campos y programa asumiendo que siempre llega.

2. Categorías de error

3. Errores de validación — type: “PARAMETER”

Se generan cuando el request contiene campos con formato incorrecto, valores fuera de rango o campos requeridos ausentes. El campo param identifica el campo específico. Todos son prevenibles validando el payload en tu sistema de caja antes de llamar a la API.

Cuando el type es PARAMETER, el code también puede ser un código numérico del rango 2002 a 2021, además del código de formato BAD_FORMAT.

3.1 Códigos de sistema

3.2 Validadores de monto y campos de pago

3.3 Validadores de cuotas (deferred)

Las cuotas viajan en el objeto deferred en todos los mercados salvo México, que usa el booleano query_deferred. Los dos son mutuamente excluyentes y nunca viajan juntos. Estas validaciones todavía no tienen código numérico asignado:

El techo depende del mercado: México envía query_deferred como booleano, Chile admite hasta 12 meses con credit_type: "03" o hasta 48 sin él, Colombia hasta 48, y Perú de 2 a 48 para todas las redes. El contrato completo, país por país, está en Acepta pagos con Kushki One.

3.4 Validadores de identificadores de transacción

3.5 Validadores de paginación y fechas

4. Errores de terminal — type: “TERMINAL”

Se generan cuando la terminal física no puede aceptar la operación. A diferencia de los errores de hardware, indican un problema de estado o conectividad, no un fallo de componente.

5. Errores de Autenticación — type: “AUTH”

Se generan cuando las credenciales son inválidas o no alcanzan los permisos para la acción solicitada.

{
  "type": "AUTH",
  "code": "AUTH-001",
  "message": "Invalid or expired credentials"
}

6. Errores de enrutamiento e internos

type: “NOT_FOUND”

type: “INTERNAL”

7. Errores del adquirente — type: “ACQUIRER”

Los errores del adquirente Kushki se encapsulan bajo type: "ACQUIRER" con esta regla de mapeo:

• code: el código nativo del adquirente, sin cambios y sin prefijo. E020 se devuelve como E020. Los códigos de autorización son nativos de la red procesadora y se dejan intactos para mantener la trazabilidad ISO 8583 que exigen las franquicias — no esperes un prefijo ACQ-, nunca llega.
• message: idéntico al mensaje original de Kushki.
• object: incluye client_transaction_id, terminal_id y serial_number cuando corresponda.
• Estado HTTP: se conserva el que devolvió originalmente Kushki.

Error original de Kushki:

{
  "code": "E020",
  "message": "Either Invalid amount or Currency conversion field overflow"
}

Error mapeado por Kushki ONE Connect, con el mismo 400 Bad Request:

{
  "type": "ACQUIRER",
  "code": "E020",
  "param": "",
  "message": "Either Invalid amount or Currency conversion field overflow",
  "object": {
    "client_transaction_id": "1018282",
    "terminal_id": "172653",
    "serial_number": "PJ715652"
  }
}

8. Errores del fabricante — type: “TERMINAL-SUNMI”

Los errores del SDK del fabricante se encapsulan con el prefijo MAN- — un solo guión — seguido del número. El código confirmado en respuestas reales es MAN-30005: se venció el tiempo de lectura de la tarjeta o de ingreso del PIN, y se trata como una cancelación esperada, no como una falla. Para el catálogo Sunmi completo por rango funcional, pídelo al equipo de integraciones de Kushki.

{
  "type": "TERMINAL-SUNMI",
  "code": "MAN-30005",
  "message": "Input PIN timeout",
  "object": {
    "client_transaction_id": "c5a3f3be-9d6f-4d39-8af5-58dbb589af69",
    "terminal_id": "172653",
    "serial_number": "SN816265"
  }
}

9. Errores de configuración — type: “CONFIGURATION”

Se generan cuando la operación no está habilitada para esa terminal, o cuando el monto supera los límites configurados. A diferencia de los errores PARAMETER, no se corrigen modificando el payload.

{
  "type": "CONFIGURATION",
  "code": "CONF-4001",
  "message": "Tip is not enabled",
  "object": {
    "client_transaction_id": "c5a3f3be-9d6f-4d39-8af5-58dbb589af69",
    "terminal_id": "172653",
    "serial_number": "SN816265"
  }
}

10. Errores de Impresora Kushki — type: “TERMINAL-PRINTER”

Errores del hardware de impresión. Están estandarizados sin importar el fabricante de la terminal.

11. Guía rápida de diagnóstico

Para depurar un fallo de firma, este es el patrón mínimo de registro:

try {
  const res  = await fetch(url, { method: "POST", headers, body });
  const data = await res.json();

  if (!res.ok) {
    logger.error("kushki_one_error", {
      http: res.status,
      type: data.type,
      code: data.code,
      transaccion: data.object?.client_transaction_id,
      firma_presente: Boolean(headers.Authorization),
    });
  }
} catch (e) {
  logger.error("kushki_one_red", { mensaje: e.message });
}

try:
    res  = requests.post(url, headers=headers, json=payload, timeout=30)
    data = res.json()

    if not res.ok:
        logger.error("kushki_one_error", extra={
            "http": res.status_code,
            "type": data.get("type"),
            "code": data.get("code"),
            "transaccion": data.get("object", {}).get("client_transaction_id"),
            "firma_presente": "Authorization" in headers,
        })
except requests.RequestException as e:
    logger.error("kushki_one_red", extra={"mensaje": str(e)})