Toda chamada de rede precisa de um ponto em que você para de esperar. Em chamadas a LLMs, esse ponto é difícil de escolher, porque por um tempo uma resposta lenta e uma conexão morta parecem iguais.
Como funciona
Clientes HTTP dividem a espera em fases. O HTTPX, um cliente HTTP comum em Python, tem quatro:
| Timeout | Significado no HTTPX | Erro |
|---|---|---|
| Connect | Tempo máximo para estabelecer uma conexão de socket | ConnectTimeout |
| Read | Espera máxima por um chunk de dados recebidos | ReadTimeout |
| Write | Espera máxima para enviar um chunk do corpo da requisição | WriteTimeout |
| Pool | Espera máxima por uma conexão do pool | PoolTimeout |
O HTTPX puro expira por padrão após cinco segundos de inatividade de rede. O SDK Python da OpenAI define seu próprio padrão: “By default requests time out after 10 minutes” (tradução: por padrão, as requisições expiram depois de 10 minutos), lança APITimeoutError e repete duas vezes uma requisição que expirou. Por padrão, ele também repete erros de conexão e respostas 408, 409, 429 e 5xx.
from openai import OpenAI
client = OpenAI(base_url="https://inference.broadnet.ai/v1", timeout=120.0, max_retries=2)
Servidores também têm timeouts. A MDN define o 504 Gateway Timeout como um gateway ou proxy que “did not get a response in time from the upstream server” (não recebeu resposta a tempo do servidor upstream), e o 408 Request Timeout como o servidor querendo “to shut down this unused connection” (encerrar esta conexão não utilizada).
Por que isso importa
- Modelos de raciocínio demoram para começar. O raciocínio acontece antes do primeiro token visível. Um timeout de leitura curto em uma chamada sem streaming pode cortar uma requisição saudável.
- Streams detectam travamentos. Com streaming, cada chunk reinicia o cronômetro de leitura, então um travamento aparece rápido mesmo em uma resposta longa.
- Retries podem dobrar o custo. Um timeout não significa que o servidor parou. Repetir uma requisição que ainda está rodando pode gerar cobrança dupla. Use backoff exponencial com teto e uma idempotency key quando a API suportar.
Na BroadNet Inference
A referência da API da BroadNet diz para ler um stream até data: [DONE]. Se a conexão terminar antes disso, “treat the response as incomplete, record the X-Request-ID” (tradução: trate a resposta como incompleta, registre o X-Request-ID) e decida se a sua aplicação pode fazer uma nova requisição com segurança. Para 500, 502, 503 e 504, ela diz para repetir com backoff exponencial limitado; 429 significa que um limite de taxa, de concorrência, de tokens por minuto ou de gasto foi atingido. Guarde o X-Request-ID para o suporte. O guia de erros e retries e o post sobre agentes de longa duração mostram configurações que funcionam.
Erros comuns
- Deixar o padrão e não entender por que uma chamada travada bloqueia um worker por dez minutos.
- Repetir sem teto, fazendo um minuto ruim virar uma enxurrada de requisições.