Formato de respuesta
Todas las respuestas de la API siguen el formato estandarApiResponse. Esto aplica tanto
para respuestas exitosas como para errores, lo que facilita el manejo uniforme en tu codigo:
- Respuesta exitosa
- Error de validacion
- Error SIAT
- Error interno
Campos de una respuesta de error
Los campos nulos no se serializan: en un error no vas a verdata, 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”:
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.Errores de codigos (CUIS, CUFD, CUF)
Errores de codigos (CUIS, CUFD, CUF)
Estos errores estan relacionados con los codigos de seguridad que el SIAT requiere para
autorizar emisiones de facturas.
Errores de datos de factura
Errores de datos de factura
Estos errores ocurren cuando los datos enviados en la factura no cumplen con las reglas del SIAT.
Errores de certificado y autorizacion
Errores de certificado y autorizacion
Errores relacionados con el certificado digital y la autorizacion del sistema ante el SIN.
Errores de disponibilidad del SIAT
Errores de disponibilidad del SIAT
Estos errores indican que el SIAT no esta disponible o tiene problemas de servicio.
Errores de anulacion
Errores de anulacion
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: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.