Catálogo Unificado de Errores — Kushki ONE Connect

March 26, 2026

Simplificamos la gestión de errores en Kushki ONE Connect. Ante cualquier fallo en una operación, nuestra API devuelve un payload estructurado en formato JSON (LinkFailure) que estandariza la respuesta sin importar si el problema se originó en la terminal, en una validación, en la autenticación o en el adquirente. Esto te permite construir integraciones más robustas, automatizar flujos de recuperación y dejar de depender exclusivamente de los HTTP Status Codes.

Este manual es tu herramienta principal de diagnóstico. En este detallamos la estructura del nuevo modelo de datos, los catálogos de códigos por categoría, cómo mapeamos los rechazos de terceros y una guía rápida para resolver problemas comunes.

1. Modelos de Errores

Todos los errores comparten la misma estructura de respuesta. Se debe evaluar primero el campo type para clasificar la fuente del fallo y luego consultar el code correspondiente.

HTTP Status Code

El HTTP status code es coherente con el type del body. Para errores ACQUIRER, se conserva el mismo HTTP status retornado originalmente por Kushki.

Ejemplo canónico

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

2. Categorías de Error (campo type)

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

Generados cuando el request enviado contiene campos con formato incorrecto, valores fuera de rango o campos requeridos ausentes. El campo param identifica el campo específico que causó el error. Todos son 100% prevenibles validando el payload antes de llamar a la API.

3.1 Errores de Validación de Request - type: “PARAMETER”

Cuando el type es PARAMETER, el campo code es siempre un código numérico positivo del rango 2001–2037. Todos son prevenibles validando el payload en el sistema de caja antes de llamar a la API. También existen dos códigos especiales de formato de sistema.

3.2 Códigos de Sistema

3.3 Validadores de Amount y Campos de Pago (2001–2013)

3.4 Validadores de Identificadores de Transacción (2010–2015)

3.5 Validadores de Paginación y Fechas (2016-2021)

3.6 Validadores de Configuración (2022-2037)

4. Errores de Terminal — type: “TERMINAL”

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

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

Generados cuando las credenciales son inválidas o no tienen permisos suficientes para ejecutar 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 originados por el adquirente Kushki se encapsulan bajo type: ACQUIRER aplicando la siguiente regla de mapeo.

Regla de Mapeo

• code: Código Kushki original con prefijo ”ACQ-”. Ejemplo: código ”13” → ACQ-13.
• message: Igual al message original retornado por Kushki.
• object: Incluye al menos los siguientes campos cuando corresponda.
  • Client_transaction_id
  • terminal_id
  • serial_number
• HTTP status: Se conserva el mismo HTTP status retornado originalmente por Kushki.

Ejemplo de Mapeo

Error original Kushki:

HTTP/1.1 400 Bad Request
{
"code": "13",
"message": "Either Invalid amount or Currency conversion field overflow"
}

Error mapeado — respuesta de Kushki ONE Connect:

HTTP/1.1 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 (Sunmi, Landi) se encapsulan bajo type: “MANUFACTURER” con código MAN-{codigo_fabricante}. Los códigos negativos del SDK de Sunmi se documentan tal como los retorna el SDK.

Regla de Mapeo

• code: Código del SDK del fabricante con prefijo ”MAN-”. Ejemplo: código ”-2001” → MAN—2001.
• message: Mensaje original del SDK del fabricante.
• object: Incluye los siguientes campos cuando corresponda.
  • Client_transaction_id
  • terminal_id
  • serial_number

{
"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 Sunmi más frecuentes en producción

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

Errores arrojados por el hardware de la terminal. Incluye la impresora térmica integrada. Estos códigos están estandarizados independientemente del fabricante de la terminal.

10. Guía Rápida de Diagnóstico

Ante un error recibido, sigue estas recomendaciones:

• ¿type es AUTHENTICATION? → Verificar credenciales (AUTH-001) o permisos (AUTH-002).
• ¿type es PARAMETER? → Revisar el campo indicado en param. Agregar validación en el POS antes de llamar a la API.
• ¿type es TERMINAL y code es TER-002? → La terminal está offline. Verificar conectividad de red.
• ¿type es TERMINAL y code es TER-003 o TER-004? → La terminal está ocupada. Esperar que termine la operación en curso o usar abort.
• ¿type es TERMINAL y code es TER-006? → Funcionalidad no habilitada en la terminal. Contactar Operaciones Kushki para habilitar.
• ¿type es DEVICE? → Condición física del hardware. Mostrar el message al operador con instrucciones de resolución.
• ¿type es MANUFACTURER y code empieza en MAN—200? → Problema de lectura de tarjeta. Solicitar reintento al cliente.
• ¿type es MANUFACTURER y code es MAN—50020 o MAN—60001? → El cliente canceló o no ingresó el PIN. Tratar como cancelación esperada.
• ¿type es ACQUIRER? → Rechazo del procesador. Mostrar el message al cliente. Registrar el code (ej. ACQ-13) con el client_transaction_id para soporte.
• ¿type es INTERNAL o NOT_FOUND? → Registrar el payload completo y escalar a soporte técnico Kushki.