Skip to main content

Formato de respuesta

Todas las respuestas de la API siguen el formato estandar ApiResponse. Esto aplica tanto para respuestas exitosas como para errores, lo que facilita el manejo uniforme en tu codigo:

Campos de una respuesta de error

Los campos nulos no se serializan: en un error no vas a ver data, y en un exito no vas a ver error.
El objeto error no trae field, siatCode ni siatDescription. El campo con problema viene en message (en los VALIDATION_ERROR), y el texto del SIAT viene tambien en message (en los SIAT_ERROR). El codigo numerico del SIAT de una factura ya emitida se consulta en siatCodeState / siatDescription de la factura, no en el error.

Codigos HTTP


Codigos de error internos

Limites que responden 429 sin error.code. El limite general por API Key (60 requests por minuto con rafaga de 10, o el de tu plan) y el freno a credenciales invalidas (mas de 20 llaves invalidas por minuto desde una misma IP) responden 429 con Retry-After y un cuerpo minimo con message, sin error.code. En ambos casos la accion es la misma: esperar Retry-After segundos. Detalle y forma exacta en Autenticacion.

SIAT_ERROR (502) vs SIAT_UNAVAILABLE (503)

CUCU separa “el SIAT dijo que no” de “el SIAT no esta”:
Cambio de contrato (2026-09-26): un SOAP fault de credencial como API KEY NO VALIDO antes llegaba como 503 SIAT_UNAVAILABLE (y los clientes lo reintentaban sin fin). Ahora llega como 502 SIAT_ERROR y no debe reintentarse: es un problema del token delegado del contribuyente, no una caida del SIAT. Si tu integracion reintentaba ante 503, no cambies nada; si trataba 502 como reintentable, sacalo de la lista.

Errores SIAT

Cuando el SIAT (Sistema Integrado de Administracion Tributaria) rechaza una operacion, la respuesta incluye el codigo SIAT original junto con la descripcion y una solucion sugerida.
Estos errores estan relacionados con los codigos de seguridad que el SIAT requiere para autorizar emisiones de facturas.
CUCU renueva automaticamente el CUFD cada 24 horas. Si ves el error 980 de forma recurrente, contacta a soporte para verificar que el cron de renovacion esta funcionando correctamente.
Estos errores ocurren cuando los datos enviados en la factura no cumplen con las reglas del SIAT.
Para validar datos antes de emitir, usa los endpoints de sincronizacion SIAT (/api/v1/siat/sync-*) para obtener los catalogos actualizados de productos, actividades economicas, unidades de medida y metodos de pago.
Errores relacionados con el certificado digital y la autorizacion del sistema ante el SIN.
Los errores de certificado requieren accion en el portal del SIN (impuestos.gob.bo). No se pueden resolver via API. Planifica la renovacion del certificado con anticipacion (al menos 15 dias antes del vencimiento).
Estos errores indican que el SIAT no esta disponible o tiene problemas de servicio.
CUCU detecta automaticamente cuando el SIAT no esta disponible y sugiere activar el modo contingencia. En contingencia, las facturas se emiten con CUF offline y se sincronizan automaticamente cuando el SIAT vuelve a estar disponible.
Errores que ocurren al intentar anular una factura.

Manejo de errores en codigo

Patron basico

Patron con reintentos y backoff exponencial


Resolucion de errores con AI

CUCU incluye un endpoint de IA que puede analizar errores del SIAT y sugerir soluciones automaticamente:
La respuesta se basa en la normativa SIAT indexada y en errores ya resueltos; detalle en AI.

Checklist de debugging

Cuando algo falla, sigue este orden:
1

Revisa el codigo HTTP

El codigo HTTP te dice la categoria general del error. Los 4xx son errores de tu lado (datos, autenticacion, permisos). Los 5xx son errores del servidor o del SIAT.
2

Lee el campo error.code

El codigo interno de CUCU te dice exactamente que tipo de error es. Usa las tablas de arriba para determinar si es retriable o no.
3

Lee message

message tiene el texto legible. Si es un VALIDATION_ERROR, lista cada campo invalido con su motivo (ruta.campo: motivo; ...). Si es un SIAT_ERROR, trae el texto con el que el SIAT rechazo la operacion.
4

Si es un 500, guarda la referencia

error.details trae ref=<uuid>. El mensaje interno (SQL, hosts, rutas) ya no viaja en la respuesta: queda en los logs de CUCU bajo esa referencia. Mandala a soporte junto con el timestamp.
5

Si es un 429, respeta Retry-After

Puede ser el limite por API Key, el cupo de reenvio de correo o el freno a credenciales invalidas desde tu IP. En los tres casos el header Retry-After dice cuantos segundos esperar.
6

Usa el endpoint de AI si no encuentras la solucion

POST /api/v1/ai/resolve-error puede analizar el error y sugerir la solucion correcta basandose en la documentacion del SIAT y errores previamente resueltos.