# Códigos de error: Reportes IA (beta)

> Conversación con la IA de reportes, Zauru vía Coli, pruebas guardadas, contexto y topes de costo. Los códigos del motor copiado de CooliAi (`src/ai/coli-core`) se documentan en ese repo.

**Cómo se detecta (toda la familia):** Lo que pasa DENTRO de un turno (Coli caído, Luna sin cuota, tope del día) no es un error HTTP: llega como aviso en el stream y queda en `ai_report_turns.trace_json` (diagnóstico) y en el `mode` del turno.

**Qué hacer (toda la familia):** Los de configuración (falta `GENERATIVE_API_KEY`, `COLI_URL` o `COLI_SERVICE_SECRET`) se arreglan en Render. Los de tope se reinician al día siguiente (día de Guatemala). Los de Coli: revisar su `/v1/health` y su log.

Lo que un código no dice lo hereda de la familia.

## `AI_REPORTS_COLI_UNAVAILABLE`

- **Tipo:** HTTP · **HTTP:** 503 · **Estado:** vigente
- **Qué significa:** No se pudo guardar el contexto de Zauru porque Coli no está configurado o no respondió (503).

## `AI_REPORTS_CONTEXT_INVALID`

- **Tipo:** HTTP · **HTTP:** 400 · **Estado:** vigente
- **Qué significa:** Una entrada del contexto no cumple el esquema estricto del motor o está repetida (400). El mensaje dice qué campo.

## `AI_REPORTS_CONVERSATION_NOT_FOUND`

- **Tipo:** HTTP · **HTTP:** 404 · **Estado:** vigente
- **Qué significa:** La conversación no existe, está archivada o es de otra persona (404; no se confirma que exista).

## `AI_REPORTS_ENTITY_BUDGET`

- **Tipo:** detalle · **HTTP:** — · **Estado:** vigente
- **Qué significa:** La entidad llegó al gasto máximo del día en Reportes IA, sumando a todas sus personas (aviso del turno, `mode = 'limit'`).

## `AI_REPORTS_PERSON_BUDGET`

- **Tipo:** detalle · **HTTP:** — · **Estado:** vigente
- **Qué significa:** La persona llegó al gasto máximo del día en Reportes IA (aviso del turno, `mode = 'limit'`).

## `AI_REPORTS_PERSON_TURNS`

- **Tipo:** detalle · **HTTP:** — · **Estado:** vigente
- **Qué significa:** La persona llegó al máximo de mensajes del día en Reportes IA. No es HTTP: llega como aviso del turno y el turno queda con `mode = 'limit'`. Se reinicia al día siguiente de Guatemala.

## `AI_REPORTS_TEST_NOT_FOUND`

- **Tipo:** HTTP · **HTTP:** 404 · **Estado:** vigente
- **Qué significa:** El caso de prueba o la corrida no existe en esta entidad (o el caso fue retirado).

## `AI_REPORTS_TEST_RUN_ACTIVE`

- **Tipo:** HTTP · **HTTP:** 409 · **Estado:** vigente
- **Qué significa:** Ya hay una corrida de pruebas en curso en la entidad (409). Una a la vez; una corrida de más de 30 minutos se da por interrumpida.

## `auth`

- **Tipo:** interno · **HTTP:** — · **Estado:** vigente
- **Qué significa:** OpenAI rechazó la credencial de Luna o el acceso al modelo (401/403). Revisar `GENERATIVE_API_KEY` en Render; el turno sigue en contingencia.

## `budget`

- **Tipo:** interno · **HTTP:** — · **Estado:** vigente
- **Qué significa:** Luna no se llamó porque el presupuesto del turno o del día ya se gastó (interno de Reportes IA; llega como aviso).

## `coli_bad_response`

- **Tipo:** interno · **HTTP:** 502 · **Estado:** vigente
- **Qué significa:** Coli respondió algo que no cumple el contrato v2 (esquema estricto): BoostAPI no lo muestra como reporte.

## `coli_error`

- **Tipo:** interno · **HTTP:** — · **Estado:** vigente
- **Qué significa:** Coli respondió un error sin código propio (status no 2xx). Revisar su log.

## `coli_not_configured`

- **Tipo:** interno · **HTTP:** 503 · **Estado:** vigente
- **Qué significa:** Faltan `COLI_URL` o `COLI_SERVICE_SECRET` en BoostAPI: no hay reportes de Zauru en Reportes IA.

## `coli_unreachable`

- **Tipo:** interno · **HTTP:** 503 · **Estado:** vigente
- **Qué significa:** No hubo respuesta de Coli (caído, red o tiempo agotado). El turno dice que Zauru no respondió y no muestra datos inventados.

## `invalid_request`

- **Tipo:** interno · **HTTP:** — · **Estado:** vigente
- **Qué significa:** OpenAI rechazó la solicitud de Luna (400/422): suele ser un parámetro del modelo no soportado. El turno sigue en contingencia.

## `model_not_available`

- **Tipo:** interno · **HTTP:** — · **Estado:** vigente
- **Qué significa:** OpenAI respondió 404 por el modelo de Luna configurado (`GENERATIVE_MODEL`): no está disponible para esa cuenta. El turno sigue en contingencia.

## `not_configured`

- **Tipo:** interno · **HTTP:** — · **Estado:** vigente
- **Qué significa:** Falta `GENERATIVE_API_KEY`: Reportes IA responde en contingencia (sin Luna, con el motor y plantillas).

## `rate_limited`

- **Tipo:** interno · **HTTP:** — · **Estado:** vigente
- **Qué significa:** OpenAI limitó la tasa o la cuota de Luna (429). El turno cae a contingencia o muestra lo que ya obtuvo.

## `timeout`

- **Tipo:** interno · **HTTP:** — · **Estado:** vigente
- **Qué significa:** Luna no respondió a tiempo. El turno cae a contingencia o muestra lo que ya obtuvo.

## `unavailable`

- **Tipo:** interno · **HTTP:** — · **Estado:** vigente
- **Qué significa:** No se pudo conectar con OpenAI o su respuesta falló. El turno cae a contingencia o muestra lo que ya obtuvo.