> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kairoconnect.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Errores frecuentes

> Códigos HTTP, formato RFC 7807 y causas habituales en Kairo Shield

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

```json theme={null}
{
  "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](mailto:tecnologia@kairoconnect.com)**