# Códigos de error: Reportes IA: motor interno de Boost

> Reportes internos de Boost para la IA de reportes (`InternalReportsService`, `src/ai/internal/`): cartera, asignaciones, cotizaciones, oportunidades y resumen de compras, con el alcance real de `RecordsAccessService`, recetas y Sistema 0 por entidad y el glosario de Boost de cada entidad (tablas `ai_report_*`, `sql/ai/ai-reportes-motor.sql`). Los estados de un reporte (`decision_unavailable`, `source_unavailable`, `forbidden`…) no son excepciones: viajan en el `status`/`reason` del resultado.

**Cómo se detecta (toda la familia):** La respuesta (`code`). Tablas que faltan: aviso `ai_report_… no está disponible` en el log de Render (una vez por proceso).

**Qué hacer (toda la familia):** El mensaje dice qué falta. Si es una tabla, aplica `sql/ai/ai-reportes-motor.sql` (con autorización de Roor en producción).

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

## `ai_report_knowledge_conflict`

- **Tipo:** HTTP · **HTTP:** 409 · **Estado:** vigente
- **Qué significa:** Dos personas cambiaron el glosario de Boost de la misma entidad a la vez: la segunda no se guardó (llave única entidad + versión).
- **Qué hacer:** Volver a cargar el glosario y aplicar el cambio otra vez.

## `ai_report_knowledge_invalid`

- **Tipo:** HTTP · **HTTP:** 400 · **Estado:** vigente
- **Qué significa:** El glosario de Boost enviado no cumple el esquema estricto (`src/ai/coli-core/knowledge.ts`), repite un id, pasa de 200 entradas o nombra una capacidad, métrica o desglose que no existe en el catálogo de Boost. No se guardó nada.
- **Qué hacer:** Corregir las entradas que lista `issues` y volver a enviar.

## `ai_report_knowledge_unavailable`

- **Tipo:** HTTP · **HTTP:** 503 · **Estado:** vigente
- **Qué significa:** No se pudo leer o escribir `ai_report_knowledge_entries` (tabla sin aplicar o base caída). El glosario no se guardó.
- **Causa típica:** Falta el DDL `sql/ai/ai-reportes-motor.sql` o la base no responde.
- **Qué hacer:** Aplicar el DDL (con autorización) o reintentar cuando la base responda.

## `ai_report_no_entity`

- **Tipo:** HTTP · **HTTP:** 403 · **Estado:** vigente
- **Qué significa:** La sesión no tiene una entidad activa: sin entidad no hay glosario ni reportes internos.

## `ai_report_recipe_not_found`

- **Tipo:** HTTP · **HTTP:** 404 · **Estado:** vigente
- **Qué significa:** La receta de reporte interno no existe en la entidad de la sesión (las recetas son por entidad; otra entidad recibe 404 aunque el id exista).

## `ai_report_source_unavailable`

- **Tipo:** HTTP · **HTTP:** 503 · **Estado:** vigente
- **Qué significa:** No se pudieron leer los vendedores visibles de la persona en la base de Boost (consulta de solo lectura caída o lenta).
- **Qué hacer:** Reintentar; si persiste, revisar la base en Render.