# Códigos de error: Zauru (sesión, GraphQL, app)

> Boost habla con Zauru por la sesión web, por GraphQL (solo lectura) y por la app. Casi todo lo que lee o escribe de ventas depende de que la sesión de la persona en Zauru esté viva.

**Cómo se detecta (toda la familia):** La respuesta trae el `code`. Los 503 (`zauru_timeout`, `zauru_unreachable`, `zauru_error`) suelen venir en ráfaga en varias pantallas a la vez (inbox y catálogo fallan juntos). Render: filtrar peticiones 503 por `path`.

**Qué hacer (toda la familia):** Timeout o caída: reintentar; si persiste, confirmar que Zauru responde. Sesión vencida o sin configuración: la persona vuelve a iniciar sesión; si Zauru la manda a `/apps/index`, le falta configuración en Zauru.

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

## `zauru_app_credentials_invalid`

- **Tipo:** HTTP · **HTTP:** 401 · **Estado:** vigente
- **Qué significa:** Faltan las credenciales de la app de Zauru (usuario y apikey) para abrir la sesión.

## `zauru_attachment_request_failed`

- **Tipo:** detalle · **HTTP:** — · **Estado:** vigente
- **Qué significa:** Zauru no aceptó subir un adjunto (PDF o imagen) a una orden o cotización. Viene como renglón de `errors[]`; lo demás de la operación puede haberse hecho.

## `zauru_config_missing`

- **Tipo:** HTTP · **HTTP:** 403 · **Estado:** vigente
- **Qué significa:** La persona tiene credenciales válidas pero a su usuario de Zauru le falta una habilitación para usar Boost: Zauru la redirige a `/apps/index`.
- **Causa típica:** El usuario no tiene la app de Boost (o su configuración) habilitada en Zauru. No es un problema del CRM.
- **Cómo detectarlo:** Render: `Zauru config missing for … respondio 302 -> …/apps/index`. La persona ve el mensaje «Tu usuario no tiene todas las configuraciones necesarias…».
- **Qué hacer:** Habilitarle la configuración en Zauru (lo hace el administrador de Zauru). No hay que tocar nada en Boost.

## `zauru_entity_mismatch`

- **Tipo:** HTTP · **HTTP:** 409 · **Estado:** vigente
- **Qué significa:** La entidad de Zauru elegida no corresponde a la entidad activa del CRM.

## `zauru_entity_switch_failed`

- **Tipo:** HTTP · **HTTP:** 503 · **Estado:** vigente
- **Qué significa:** Zauru respondió con error al pedido de cambiar de entidad.

## `zauru_entity_switch_not_applied`

- **Tipo:** HTTP · **HTTP:** 409 · **Estado:** vigente
- **Qué significa:** Zauru aceptó el cambio de entidad pero la entidad activa no cambió.

## `zauru_error`

- **Tipo:** HTTP · **HTTP:** 503 · **Estado:** vigente
- **Qué significa:** Zauru respondió con error a una consulta de GraphQL. El mensaje pide reintentar en unos segundos.

## `zauru_identity_mismatch`

- **Tipo:** HTTP · **HTTP:** 401, 409 · **Estado:** vigente
- **Qué significa:** Las credenciales de la app de Zauru son de otro usuario de Zauru que el de la sesión.

## `zauru_session_expired`

- **Tipo:** HTTP · **HTTP:** 401 · **Estado:** vigente
- **Qué significa:** La sesión de la persona en Zauru venció.
- **Qué hacer:** Volver a iniciar sesión en Boost (renueva la sesión de Zauru).

## `zauru_session_missing`

- **Tipo:** HTTP · **HTTP:** 428 · **Estado:** vigente
- **Qué significa:** La sesión no tiene guardada la URL de GraphQL de Zauru (428): hay que volver a iniciar sesión.

## `zauru_timeout`

- **Tipo:** detalle, HTTP · **HTTP:** 503 · **Estado:** vigente
- **Qué significa:** Zauru tardó demasiado en responder y Boost cortó la espera (503).
- **Causa típica:** Zauru lento o una consulta pesada (catálogo grande, facturas de muchos meses). El tope de la app es `ZAURU_APP_FETCH_TIMEOUT_MS` (10 s por defecto).
- **Cómo detectarlo:** Varias pantallas fallan a la vez con 503 (catálogo, compositor de cotizaciones, dashboard). En Render, peticiones 503 en las rutas del catálogo, del compositor de cotizaciones y del catálogo del chat.
- **Qué hacer:** Reintentar en unos segundos. Si una pantalla falla siempre, la consulta es demasiado grande: acotar la ventana o paginar (no subir el tope a ciegas).

## `zauru_unreachable`

- **Tipo:** detalle, HTTP · **HTTP:** 503 · **Estado:** vigente
- **Qué significa:** No se pudo conectar con Zauru (red, DNS o Zauru caído) (503).
- **Cómo detectarlo:** Como `zauru_timeout`, pero el mensaje dice «No se pudo conectar con Zauru».
- **Qué hacer:** Confirmar que Zauru responde; reintentar cuando vuelva.

## `zauru_upstream_error`

- **Tipo:** HTTP · **HTTP:** 503 · **Estado:** vigente
- **Qué significa:** Zauru respondió con un status de error a un pedido de la sesión web (503).