Errores frecuentes - Kairo Connect Docs

Los errores de Kairo Shield siguen RFC 7807 (Problem Details for HTTP APIs):

{
  "type": "about:blank",
  "title": "Validation Error",
  "status": 422,
  "detail": "Request validation failed",
  "errors": [
    {
      "field": "body.amount",
      "message": "Input should be greater than 0",
      "type": "greater_than"
    }
  ]
}

El campo errors solo aparece en errores de validación (422).

Códigos HTTP

Código	Título típico	Cuándo ocurre
401	Unauthorized	API Key ausente o inválida
403	Forbidden	Cliente suspendido, onboarding, o consentimiento de fraude no otorgado
409	Duplicate Transaction	Mismo `transaction_id` dentro de la ventana de idempotencia (24 h)
422	Validation Error	Datos inválidos (UUID, amount ≤ 0, enum desconocido, etc.)
429	Too Many Requests	Rate limit excedido
503	Service Unavailable	Modo mantenimiento activo
504	Scoring Timeout	El scoring superó el SLA (`scoring_timeout_ms`)
500	Internal Server Error	Error inesperado; contacte soporte con `request_id` si está disponible

Errores de scoring

Situación	Código	Acción recomendada
`transaction_id` duplicado	409	Use un UUID nuevo o recupere el score cacheado del primer envío
Timeout de inferencia	504	Reintente con backoff; reporte si persiste
Consentimiento no otorgado	403	Solicite activación a Kairo Connect

Soporte

Al reportar incidencias incluya el request_id de la respuesta de scoring cuando esté disponible. tecnologia@kairoconnect.com