API Timeout: cómo diagnosticar desconexiones y decidir un reintento seguro
Guía práctica para localizar timeouts de API LLM, cambiar solo el límite responsable y validar la recuperación con reintentos seguros.
Índice
API Timeout: cómo diagnosticar desconexiones y decidir un reintento seguro
Un API Timeout significa que algún participante de la ruta dejó de esperar. El cliente pudo no conectarse, un proxy pudo cerrar un stream inactivo, venció el deadline total de la aplicación o el gateway no recibió a tiempo la respuesta upstream. El mensaje por sí solo no demuestra que el modelo esté caído.
Antes de reintentar, registre la excepción, el estado HTTP y el cuerpo si existen, el tiempo transcurrido, el request ID y si llegó algún chunk. Cambie únicamente el límite de la capa confirmada; ampliar todos los timeouts oculta la causa y puede repetir una operación con resultado desconocido.
Si la solicitud usó BetterToken, abra el Dashboard antes del reintento y compare hora, modelo, estado y uso de Tokens. Así separa de inmediato una solicitud que llegó a la API de un fallo anterior al gateway.
Por qué un timeout no tiene una sola causa
Aplicación / SDK
→ DNS y TCP/TLS
→ proxy corporativo o reverse proxy
→ API gateway
→ modelo upstream
→ respuesta streaming al clienteEl connect timeout cubre DNS, TCP y TLS. El read o stream-idle timeout indica que no llegó el siguiente chunk dentro del límite del cliente. El pool timeout ocurre al esperar una conexión libre. El deadline total limita toda la operación de negocio, mientras que el upstream timeout pertenece por separado al gateway o proveedor. Cambiar uno no amplía los demás.
Cómo localizar la capa de la caída
| Señal | Capa probable | Siguiente comprobación |
|---|---|---|
httpx.ConnectTimeout, sin respuesta HTTP | DNS, TCP o TLS | Reproducir desde el mismo entorno; comparar DNS, CA, proxy y firewall |
httpx.ReadTimeout antes o entre chunks | Read/idle del cliente o proxy intermedio | Medir primer byte e intervalos; revisar límites idle del proxy |
| Hay estado HTTP y cuerpo de error | Gateway o upstream | Guardar estado, cuerpo y request ID; seguir el contrato de error del proveedor |
httpx.PoolTimeout | Pool del cliente | Medir concurrencia y ocupación; cambiar límites solo si se confirma saturación |
| Cancelación tras el mismo tiempo total | Aplicación, job runner o reverse proxy | Identificar al propietario del deadline y compararlo con temporizadores inferiores |
Siga este orden: conserve la señal, reproduzca desde el mismo host o contenedor, revise cada proxy intermedio y después evalúe gateway o upstream. Mantenga modelo, prompt, red, endpoint y proxy constantes; cambie una sola variable por prueba.
HTTPX documenta timeouts independientes de connect, read, write y pool. Los valores concretos no son universales: deben derivarse de las mediciones, las pausas esperadas entre chunks y el deadline total.
Cuándo cambiar el timeout, la salida o el retry
- Cambie connect timeout solo si se confirma que DNS/TCP/TLS tarda demasiado.
- Cambie read o idle timeout si la conexión existe y un límite intermedio confirmado vence entre chunks.
- Amplíe el deadline total solo si la operación puede durar más y las capas inferiores funcionan.
- Reduzca o divida la salida cuando solo falle la prueba larga controlada; no lo convierta en explicación sin mediciones.
- Trate
429y el desbordamiento de contexto por separado: no son connect timeout.
Retry seguro sin duplicar una operación desconocida
Después del envío, un timeout es primero un resultado desconocido. Un task ID local ayuda a correlacionar logs, pero no impide una segunda operación del servidor. Repita automáticamente solo si existe idempotencia o consulta de estado documentada y una evidencia externa muestra que la primera solicitud no fue aceptada.
Lista mínima:
- Conservar request ID, estado/cuerpo, timestamps y chunks recibidos.
- Antes de repetir una acción no idempotente, comprobar su resultado real.
- No reenviar automáticamente un stream parcial: puede crear otra generación y consumo adicional.
- Limitar número de intentos y deadline total; sumar retries del SDK, proxy y aplicación.
- Capturar también errores durante la iteración SSE, no solo al crear el objeto response.
Dos pruebas confirman la reparación
- Solicitud corta: pida una respuesta pequeña y registre estado, tiempo al primer byte, duración, request ID y fin del stream. Si falla, revise conexión, autenticación y endpoint.
- Solicitud larga controlada: tras el éxito anterior, aumente solo la salida esperada o restaure la carga original. Mantenga modelo, endpoint, red y proxy. Si solo falla esta prueba, compare read/idle timeout, deadline total y límites intermedios.
La reparación queda confirmada cuando la prueba corta y una repetición del escenario original terminan con el resultado esperado y sin duplicados inexplicables. Si la solicitud llegó a BetterToken, compare en el Dashboard hora, modelo, estado y uso de Tokens y luego verifique el contrato del endpoint.
