Catálogo de errores

Referencia única de todos los motivo de rechazo que puede devolver el API. Cada motivo incluye su causa, en qué etapa del pipeline ocurre, la forma de su payload y qué debe hacer Jaremar.

Tabla maestra

motivo	Alcance del rechazo	Etapa	HTTP
FECHAS_INVALIDAS	Batch completo	3	422
MANIFIESTOS_FECHA_INVALIDA	Batch completo	4	422
ALMACENES_DESCONOCIDOS	Por manifiesto	7	422
MANIFIESTO_CERRADO	Por manifiesto	7	422
FACTURAS_DUPLICADAS_EN_OTRO_MANIFIESTO	Por manifiesto	7	422
MOTIVOS_MIXTOS	Por manifiesto (varios)	7	422

Alcance “batch completo”: ninguna factura entra. Alcance “por manifiesto”: las facturas de manifiestos válidos sí entran; solo se rechazan las de los manifiestos afectados.

---

Rechazos de batch completo

FECHAS_INVALIDAS

Agrupa los rechazos de las reglas de fecha. La validación es por factura y atómica por manifiesto: una sola factura inválida rechaza el manifiesto completo. La mezcla de fechas dentro de un manifiesto está permitida (por defecto). Cada manifiesto rechazado trae su propio sub-motivo en manifiestos_rechazados[].motivo:

Sub-motivo	Causa
FECHA_FACTURA_FUTURA	Alguna FechaFactura es posterior a hoy.
FECHA_FACTURA_DEMASIADO_ANTIGUA	Alguna FechaFactura supera los 30 días de antigüedad.
FECHA_FACTURA_INVALIDA	Alguna FechaFactura no se pudo interpretar.
FECHAS_MEZCLADAS	Solo si Hosana activa el modo estricto: el manifiesto mezcla fechas.

Acción: corrige las fechas en origen y reenvía. La respuesta incluye manifiestos_validos[] para que sepas cuáles estaban bien.

MANIFIESTOS_FECHA_INVALIDA

Se intentó agregar facturas a un manifiesto que ya existe en Hosana y fue creado en un día anterior. Un manifiesto ya creado no acepta facturas nuevas en días posteriores (no crece día tras día).

{
  "manifiesto": "800003",
  "fecha_original": "2026-06-05",
  "fecha_intento": "2026-06-06",
  "total_facturas": 122,
  "facturas_afectadas": ["002-001-01-04002050", "002-001-01-04002051"],
  "instruccion": "El manifiesto #800003 fue creado el 2026-06-05 y ya no acepta facturas nuevas. Reenvíe estas facturas en un nuevo número de manifiesto."
}

Acción: reenvía esas facturas bajo un número de manifiesto nuevo. La respuesta trae manifiestos_no_afectados[] con los manifiestos válidos que debes reenviar solos.

---

Rechazos por manifiesto

Ocurren durante el procesamiento (paso 7). Las facturas de los manifiestos válidos del mismo batch sí se insertan.

ALMACENES_DESCONOCIDOS

El manifiesto contiene facturas con un código de Almacen que no existe en Hosana (los válidos son OAC, OAS, OAO).

{
  "manifiesto": "800003",
  "total_facturas": 122,
  "motivo": "ALMACENES_DESCONOCIDOS",
  "almacenes_desconocidos": [
    { "almacen": "OAX", "facturas": ["002-001-01-04002050", "002-001-01-04002051"], "cantidad": 2 }
  ]
}

Acción: corrige el código de bodega (o solicita a Hosana que registre la bodega) y reenvía el manifiesto limpio. Un Almacen vacío se reporta como (vacío).

MANIFIESTO_CERRADO

El manifiesto ya está cerrado en Hosana y no acepta modificaciones.

{
  "manifiesto": "800003",
  "total_facturas": 122,
  "motivo": "MANIFIESTO_CERRADO",
  "mensaje": "El manifiesto #800003 está cerrado y no acepta modificaciones."
}

Acción: no se pueden agregar facturas a un manifiesto cerrado. Reenvía las facturas bajo un manifiesto nuevo, o coordina con Hosana si fue un cierre prematuro.

FACTURAS_DUPLICADAS_EN_OTRO_MANIFIESTO

Una o más facturas del manifiesto ya existen en Hosana bajo un manifiesto distinto. Una factura solo puede pertenecer a un manifiesto.

{
  "manifiesto": "800003",
  "total_facturas": 122,
  "motivo": "FACTURAS_DUPLICADAS_EN_OTRO_MANIFIESTO",
  "mensaje": "El manifiesto #800003 contiene facturas que ya existen en otros manifiestos. Reenvíelo limpio.",
  "facturas_duplicadas": [
    { "factura": "002-001-01-04001001", "manifiesto_existente": "800002" }
  ]
}

Acción: revisa por qué esas facturas aparecen en dos manifiestos. Quita las duplicadas y reenvía el manifiesto limpio. El campo manifiesto_existente te dice dónde está ya registrada cada factura.

MOTIVOS_MIXTOS

No es un motivo en sí, sino un indicador: varios manifiestos del batch fueron rechazados por motivos distintos. El motivo raíz será "MOTIVOS_MIXTOS" y debes leer el motivo propio de cada entrada en manifiestos_rechazados[].

Acción: procesa cada entrada de manifiestos_rechazados[] según su propio motivo, usando las secciones de arriba.

---

Errores que no son rechazos de negocio

Situación	HTTP	Cómo se reconoce
Body no es un array no vacío	422	message específico, sin motivo.
Faltan campos obligatorios	422	Arreglo errores[] con el detalle por factura.
ApiKey ausente o inválido	401	Ver autenticación.
Servidor sin clave configurada	503	Problema del lado de Hosana.
Rate limit superado	429	Ver rate limits.
Error interno	500	batch_uuid presente para rastreo.

Regla de oro para tu integración

1. ¿HTTP 401/429/500/503?  → problema de transporte/infra. Maneja según el código.
2. ¿HTTP 200 y success:true? → leer resumen. (Ojo: puede haber pendientes_revision.)
3. ¿HTTP 422? → leer 'motivo':
      - FECHAS_INVALIDAS / MANIFIESTOS_FECHA_INVALIDA → nada entró, corrige y reenvía.
      - ALMACENES.../MANIFIESTO_CERRADO/FACTURAS_DUP... → parte entró; corrige los
        manifiestos rechazados y reenvíalos solos.
      - MOTIVOS_MIXTOS → recorre manifiestos_rechazados[] y trata cada uno por su motivo.
      - sin 'motivo' pero con 'errores' → corrige estructura del payload.

Ver la guía completa en cómo reaccionar a un rechazo.