Errores 409, lentitud e intermitencias del SII

API Gateway es una pasarela: cualquier intermitencia del SII llega hasta tu integración. Lo importante es saber cuándo el problema realmente es del SII, porque a menudo no lo es.

El mensaje

{
  "code": 409,
  "detail": "Los servidores del SII no han respondido de manera satisfactoria, están con problemas de caída o de capacidad (HTTP 503). Se recomienda esperar y reintentar la consulta más tarde."
}

Si es intermitente: espera y reintenta

Si el error aparece a veces y otras veces la consulta funciona, es una intermitencia real. Espera y reintenta más tarde. No hay una ventana horaria garantizada, aunque las horas de menor carga suelen dar mejores resultados.

Las mantenciones programadas del SII se publican en el blog.

Si es permanente: probablemente no es el SII

Este es el diagnóstico clave. Si un recurso devuelve 409 siempre, en distintos días y horarios, mientras otros recursos del mismo producto funcionan con las mismas credenciales, el mismo token y el mismo proxy, la causa está en tu request.

Dos casos reales que se veían exactamente así:

Filtros en el nivel equivocado. Los filtros de los recursos del Portal MiPYME deben ir anidados dentro de un objeto filtros. Enviarlos al nivel raíz producía 409/503 de forma constante durante días.

Método de autenticación equivocado. El mismo recurso consultado con certificado digital, cuando la documentación indica RUT y clave de un usuario autorizado, devolvía 409/503 de forma reproducible.

Revisa además que el rango de fechas cubra un mes como máximo y que el valor de ESTADO esté en la lista válida del recurso.

La prueba que separa un caso del otro

Si el listado falla con 409 pero la descarga de PDF del mismo módulo funciona, con las mismas credenciales y la misma configuración, el problema está en la petición del listado. Una caída del SII afectaría a ambos.

Lentitud

Tres explicaciones posibles:

Algunas operaciones son lentas por diseño. Cada consulta implica iniciar sesión en el SII y navegar por su sitio: de 4 a 8 segundos es normal en operaciones autenticadas. La primera consulta de una serie es la más lenta porque abre la sesión; las siguientes la reutilizan.

Intermitencia del SII. Si un recurso que respondía en 2 o 3 segundos pasa a tardar 30, y otros funcionan bien, lo más probable es el SII.

Tu proxy no responde. El síntoma característico: consultas que quedan procesando varios minutos, con tiempos casi idénticos entre sí, y terminan en 400 o directamente sin respuesta. Revisa Errores de proxy.

Dimensiona bien tus timeouts

Un timeout de 30 segundos es insuficiente para operaciones que autentican en el SII. Si tu cliente aborta antes de que la API responda, verás un error de cancelación en tu lado mientras la petición sigue procesándose del nuestro, lo que dificulta el diagnóstico.

Pero dimensionar bien no es poner el número más alto posible. Una operación autenticada tarda de 4 a 8 segundos, y un margen holgado cubre de sobra cualquier lentitud real del SII. Si tu cliente ya espera minutos y aun así no alcanza, subir el timeout no resuelve nada: solo alarga la espera antes del mismo error. Un timeout de esa magnitud que no alcanza es un síntoma, no la causa, y lo que corresponde es buscar por qué la consulta no está terminando.

Compara el tiempo que mide tu cliente con el que registra el dashboard de la conexión: si tu cliente cortó antes, la diferencia lo delata.

Antes de subir el timeout, descarta el proxy

Subir el timeout solo ayuda cuando la API responde, y tarde. Si la petición queda colgada y siempre termina cancelada por tu cliente, con tiempos casi idénticos entre una y otra, eso no es lentitud: lo más probable es que la salida al SII no se esté completando. Un proxy inalcanzable no devuelve error, deja la consulta esperando. Revisa Errores de proxy antes de tocar el timeout.

Si tu cliente canceló, ¿alcanzó a ejecutarse la operación?

Cuando tu cliente aborta te quedas sin respuesta, pero del lado nuestro la petición siguió su curso. Antes de reintentar —y con más razón si la operación emite un documento, porque un reintento a ciegas puede duplicarlo— compruébalo en el panel “Actividad reciente (Últimas 10 peticiones)” del dashboard de la conexión, donde cada llamada queda con su endpoint, su código de respuesta, los créditos consumidos y el tiempo real que tomó. Míralo cuanto antes: solo conserva las diez peticiones más recientes.

Lo que ves en el panel	Qué significa
Aparece con un código de éxito	Se ejecutó. Confírmalo en el recurso de consulta del producto antes de volver a emitir
Aparece con un código de error	La operación falló. Puedes reintentar
No aparece	No es concluyente. Espera y vuelve a mirar antes de reintentar

Que no aparezca no significa que no haya llegado

El registro se escribe cuando la petición termina. Mientras sigue en curso —y una consulta detenida en un proxy que no responde puede seguir en curso varios minutos después de que tu cliente se rindió— no figura en el panel. La ausencia no distingue entre “nunca llegó” y “todavía se está ejecutando”. Espera a que cierre y vuelve a mirar.

¿Está caído el servicio?

Antes de concluirlo, descarta en orden:

¿Es el día 1 del mes o pasó hace poco? Puede ser una suspensión por créditos: la API responde La conexión está inactiva.
¿Qué dice exactamente el error? No todos son caídas: 401 es token o conexión, 403 productos, 402 créditos o IP, 400 con detalle de proxy es tu proxy.
¿Falla un recurso o todos? Si falla uno solo, no es una caída.
¿Tu proxy sigue arriba y con la misma IP?
¿El SII está operativo? Entra manualmente al portal con las mismas credenciales. Si tampoco funciona ahí, la falla es del SII.