Catálogo Unificado de Errores — Kushki ONE Connect

04 agosto 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.

El código de estado HTTP es coherente con el type del cuerpo. Para errores ACQUIRER se conserva el estado que devolvió originalmente Kushki.

{
  "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."
  }
}

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 2001 a 2037, además de dos códigos especiales de formato.

3.1 Códigos de sistema

3.2 Validadores de monto y campos de pago

3.3 Validadores de identificadores de transacción

3.4 Validadores de paginación y fechas

3.5 Validadores de configuración

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: “AUTHENTICATION”

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

{
  "type": "AUTHENTICATION",
  "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: código Kushki original con el prefijo ACQ-. El código 13 se convierte en ACQ-13.
• 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": "13",
  "message": "Either Invalid amount or Currency conversion field overflow"
}

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

{
  "type": "ACQUIRER",
  "code": "ACQ-13",
  "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: “MANUFACTURER”

Los errores del SDK del fabricante se encapsulan con el prefijo MAN- seguido del código original. El código -2001 de Sunmi se convierte en MAN--2001.

{
  "type": "MANUFACTURER",
  "code": "MAN--2001",
  "message": "Have no card",
  "object": {
    "client_transaction_id": "c5a3f3be-9d6f-4d39-8af5-58dbb589af69",
    "terminal_id": "172653",
    "serial_number": "SN816265"
  }
}

Códigos de Sunmi más frecuentes

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

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

{
  "type": "CONFIGURATION",
  "code": "-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)})