Errores de proxy y timeouts hacia el SII

El proxy es un requisito obligatorio del servicio. Cuando está ausente o mal configurado, la API no logra salir al SII y la consulta falla.

Mensajes que indican un problema de proxy

Estos mensajes vienen del propio control de proxy de la API y apuntan directamente a él:

{ "detail": "Error de conexión con el proxy. Verifique la configuración del proxy. Detalle: ... ProxyError('Unable to connect to proxy', ... [Errno 111] Connection refused)" }

{ "detail": "Error de conexión con el proxy. Verifique la configuración del proxy. Detalle: ... [Errno 101] Network is unreachable" }

Estos otros indican que la salida hacia el SII no se completó, y la causa habitual es el proxy:

{ "message": "cURL error 28: Connection timed out after 20001 milliseconds" }

{ "message": "cURL error 97: Can't complete SOCKS5 connection to zeusr.sii.cl" }

También puede manifestarse de una forma menos evidente: consultas que quedan procesando varios minutos y terminan en 400, con tiempos muy parecidos entre sí, porque la comunicación con el SII nunca se completa.

Cuando no hay ningún mensaje de error

Es el caso más difícil de diagnosticar, y el que más se confunde con lentitud del SII: la petición sale de tu aplicación, la API nunca responde, y al cabo de varios minutos es tu propio cliente el que cancela.

The request was canceled due to the configured HttpClient.Timeout of 180 seconds elapsing.

Ese error lo genera tu cliente, no la API, así que no trae ninguna pista de la causa. La primera sospecha es el proxy.

Lo determinante es cómo falla:

Cómo falla el proxy	Qué ves
Rechaza la conexión: el servicio está caído o el puerto cerrado	Un error rápido y explícito: `Connection refused`
Descarta los paquetes: un firewall o un grupo de seguridad que bloquea sin responder	Nada. La petición queda colgada hasta que alguien corta

Un bloqueo silencioso no produce error: produce espera. Por eso un proxy inalcanzable se ve igual que un SII lento, y por eso subir el timeout no sirve en este caso.

Estos otros no son exclusivamente de proxy

Los errores de navegación o de autenticación en los portales del SII —por ejemplo Page.goto: Timeout ... exceeded o Timeout esperando localStorage en el flujo OAuth de eBoleta— pueden originarse en el proxy, pero también en el formato del RUT enviado, en los permisos del usuario ante el SII o en una intermitencia del propio SII. Descarta el proxy con los pasos de abajo y, si persiste, revisa Errores 400: estructura del request y la documentación del recurso.

Cómo verificar si el proxy está operando

Revisa la cabecera X-Stats-HttpClientProxy en la respuesta:

Valor	Significado
`1`	La consulta salió por tu proxy
`0`	El proxy no se está usando

Si vale 0, revisa que la URL esté bien guardada en tu conexión y que tenga el formato correcto:

http://<usuario>:<contraseña>@<ip_del_proxy>:3128

Lista de verificación

El contenedor está arriba: docker compose ps y docker compose logs squid.
El puerto 3128 es accesible desde Internet: revisa firewall del sistema y del proveedor (grupos de seguridad, reglas de red).
Las credenciales coinciden: el usuario y la contraseña de la URL configurada en API Gateway deben ser exactamente los del archivo de contraseñas del proxy.
La IP no cambió: si tu servidor cambió de IP, la URL del proxy quedó apuntando a la anterior.
Los dominios permitidos están completos: .sii.cl, .amazonaws.com y .previred.com. Deben estar los tres: comprobar solo los del SII no basta.
Nuestra IP está permitida, si restringes por origen: obtenla con nslookup app.apigateway.cl.

Prueba tu proxy por tu cuenta desde cualquier máquina, fuera de la red donde está instalado. Desde dentro puede responder aunque no sea alcanzable desde Internet.

Primero comprueba que el puerto responda, sin meter HTTP de por medio:

nc -vz -w 5 TU_IP 3128

Resultado	Qué significa
`succeeded!`	El puerto es alcanzable. Sigue con la prueba de tráfico
`Operation timed out`	Nadie contesta: algo descarta los paquetes. Revisa firewall del sistema y del proveedor
`Connection refused`	El puerto se alcanza, pero no hay nada escuchando. El proxy está caído

Después prueba el tráfico:

curl -x http://usuario:contrasena@TU_IP:3128 https://www.sii.cl -I --max-time 15

Deberías ver HTTP/1.1 200 Connection established. Si en cambio obtienes curl: (28) Connection timed out, tu proxy no es alcanzable desde fuera: es el mismo diagnóstico del Operation timed out de arriba.

Si cualquiera de las dos pruebas falla, el problema está en tu proxy y no en API Gateway.

Un patrón que confunde

Es habitual que el proxy responda bien a tus pruebas y que, sin embargo, sus logs no muestren ninguna conexión entrante desde nuestros servidores hacia dominios del SII. Cuando ocurre eso, la conexión no está llegando a tu proxy: revisa firewall, grupos de seguridad y reglas de red del proveedor, más que la configuración de Squid.

El tutorial de proxy trae el docker-compose.yml y el squid.conf listos, y sus problemas comunes el detalle de cada punto.