Referencia de errores

En esta página encontrarás una presentación de los tipos de errores que puede devolver la API de Koncili.

---

Observaciones importantes:

• Esta tabla lista todos los errores conocidos que pueden ocurrir durante la integración con la API Koncili
• Cada error incluye un código HTTP, un código interno, con el formato {httpCode}-{internalCode} (ejemplo: 404-1), un mensaje estándar y los endpoints donde puede ocurrir
• Para errores no listados, consulta el estándar RFC 7807
• Si tienes dudas, comunícate con nuestro soporte: erp@koncili.com

Tabla de referencia

Código	Estado HTTP	Endpoints	Descripción	Solución
400-0	400	Todos los endpoints	Valores inválidos en el payload
400-2	400	Todos los endpoints	El canal no admite importación vía API
400-3	400	POST /order		Fechas en conflicto
403-1	403	Todos los endpoints	La cuenta está inactiva
403-2	403	Todos los endpoints	La cuenta no está autorizada para operar el canal
404-1	404	Todos los endpoints	La cuenta informada no existe
404-2	404	Todos los endpoints	El canal informado no existe
404-3	404	GET /order DELETE /order	El pedido indicado no existe
403	403	Todos los endpoints	{"response": "NO_TOKEN"} Token ausente o expirado	Genera un nuevo token vía /public/api/auth/token
403	403	Todos los endpoints	IP no autorizada	Habilita la IP vía /externalapi/ip-segmentation
502	502	Todos los endpoints	Falla de comunicación	Verifica el cuerpo de la solicitud y reenvíala después de algunos segundos
404	404	Todos los endpoints	Endpoint incorrecto	Confirma el endpoint en el ambiente correcto (sandbox o producción)
500	500	Todos los endpoints	Error interno de la API	Envía los detalles (endpoint, hora, cuerpo de la solicitud) a erp@koncili.com

Cómo interpretar los errores

Código de error: Combinación del estado HTTP + código único interno (p. ej.: 404-3)

1. Errores 4xx: Problemas con la solicitud
2. Errores 5xx: Problemas en el servidor (generalmente temporales)

Formato de respuesta

Las respuestas de la API tienen por defecto el siguiente formato:

{
  "errorMessage": "Channel invalid_channel not found",
  "errorCode": "404-2",
  "errorSource": "KIE"
}

Para un payload mal formado, en este ejemplo, se envía un pedido con un status no aceptado por la API:

{
  "errorMessage": "Bad Request",
  "errorDetails": [
    {
      "message": "JSON decoding error: Invalid ChannelStatusType value. Accepted values are: INVOICED, PAID_WAITING_DELIVERY, CONCLUDED, CANCELED"
    }
  ],
  "errorCode": "400-0",
  "errorSource": "KIE"
}

El campo errorSource puede tomar dos valores:

1. KIE (Koncili internal error), errores relacionados con la lógica de negocio
   • Escenarios típicos:
     • Validación de payload
     • Conflicto de datos
     • Reglas de negocio infringidas
2. TPE (Third Party Error), fallas en integraciones externas: - Escenarios típicos: - APIs de marketplaces no disponibles - Timeout en servicios asociados - Formato inesperado en respuestas externas

Flujo recomendado para el manejo

Nota

Los errores de tipo TPE generalmente se resuelven automáticamente en intentos posteriores. Si persisten por más de 15 minutos, comunícate con nuestro equipo técnico.