Toda llamada de red necesita un punto en el que se deja de esperar. En las llamadas a un LLM ese punto es difícil de elegir, porque una respuesta lenta y una conexión muerta se ven iguales durante un rato.
Cómo funciona
Los clientes HTTP dividen la espera en fases. HTTPX, un cliente HTTP habitual en Python, tiene cuatro:
| Timeout | Significado en HTTPX | Error |
|---|---|---|
| Conexión (connect) | Tiempo máximo para establecer una conexión de socket | ConnectTimeout |
| Lectura (read) | Espera máxima por un fragmento de datos entrantes | ReadTimeout |
| Escritura (write) | Espera máxima para enviar un fragmento del cuerpo de la solicitud | WriteTimeout |
| Pool | Espera máxima por una conexión del pool | PoolTimeout |
HTTPX, sin configurar, agota el tiempo tras cinco segundos de inactividad de red. El SDK de OpenAI para Python fija su propio valor: “By default requests time out after 10 minutes” (traducción: por defecto, las solicitudes agotan el tiempo de espera a los 10 minutos), lanza APITimeoutError y reintenta dos veces una solicitud que agotó el tiempo. También reintenta por defecto los errores de conexión y las respuestas 408, 409, 429 y 5xx.
from openai import OpenAI
client = OpenAI(base_url="https://inference.broadnet.ai/v1", timeout=120.0, max_retries=2)
Los servidores también tienen timeouts. MDN define 504 Gateway Timeout como un gateway o proxy que “did not get a response in time from the upstream server” (traducción: no recibió a tiempo una respuesta del servidor de origen), y 408 Request Timeout como el servidor que quiere “to shut down this unused connection” (traducción: cerrar esta conexión sin uso).
Por qué importa
- Los modelos de razonamiento tardan en empezar. El razonamiento ocurre antes del primer token visible. Un timeout de lectura corto en una llamada sin streaming puede cortar una solicitud sana.
- Los streams detectan bloqueos. Con streaming, cada fragmento reinicia el temporizador de lectura, así que un bloqueo se nota rápido incluso en una respuesta larga.
- Los reintentos pueden duplicar el costo. Un timeout no significa que el servidor se haya detenido. Reintentar una solicitud que sigue en ejecución puede cobrarse dos veces. Use backoff exponencial con un tope, y una clave de idempotencia donde la API la admita.
En BroadNet Inference
La referencia de la API de BroadNet indica leer un stream hasta data: [DONE]. Si la conexión termina antes, “treat the response as incomplete, record the X-Request-ID” (traducción: trate la respuesta como incompleta y registre el X-Request-ID), y decida si su aplicación puede enviar una nueva solicitud con seguridad. Para 500, 502, 503 y 504 indica reintentar con backoff exponencial acotado; un 429 significa que se alcanzó un límite de frecuencia, de concurrencia, de tokens por minuto o de gasto. Conserve el X-Request-ID para soporte. La guía de errores y reintentos y el artículo sobre agentes de larga duración muestran configuraciones que funcionan.
Errores comunes
- Dejar el valor predeterminado y preguntarse por qué una llamada colgada bloquea un worker durante diez minutos.
- Reintentar sin tope, de modo que un minuto malo se convierte en una avalancha de solicitudes.