API Timeout: como diagnosticar quedas e decidir uma tentativa segura
Guia prático para localizar timeouts em APIs de LLM, mudar apenas o limite responsável e validar a recuperação com duas tentativas controladas.
Conteúdo
API Timeout: como diagnosticar quedas e decidir uma tentativa segura
Um API Timeout significa que algum participante do caminho deixou de esperar. O cliente pode não ter conectado, um proxy pode ter fechado um stream ocioso, o deadline total da aplicação pode ter expirado ou o gateway pode não ter recebido a resposta upstream a tempo. A mensagem sozinha não prova indisponibilidade do modelo.
Antes de repetir, registre a classe da exceção, o status HTTP e o corpo quando existirem, o tempo decorrido, o request ID e se algum chunk chegou. Altere somente o limite da camada confirmada. Aumentar todos os timeouts esconde a causa e pode repetir uma operação com resultado desconhecido.
Se a solicitação usou BetterToken, abra o Dashboard antes do retry e compare horário, modelo, status e uso de Tokens. Isso separa imediatamente uma solicitação que chegou à API de uma falha anterior ao gateway.
Por que um timeout não tem uma causa única
Aplicação / SDK
→ DNS e TCP/TLS
→ proxy corporativo ou reverse proxy
→ API gateway
→ modelo upstream
→ resposta streaming ao clienteO connect timeout cobre DNS, TCP e TLS. O read ou stream-idle timeout indica que o próximo chunk não chegou dentro do limite do cliente. O pool timeout ocorre ao esperar uma conexão livre. O deadline total limita toda a operação de negócio, enquanto o upstream timeout pertence separadamente ao gateway ou provedor. Mudar um deles não amplia os demais.
Como localizar a camada da interrupção
| Sinal | Camada provável | Próxima verificação |
|---|---|---|
httpx.ConnectTimeout, sem resposta HTTP | DNS, TCP ou TLS | Reproduzir no mesmo ambiente; comparar DNS, CA, proxy e firewall |
httpx.ReadTimeout antes ou entre chunks | Read/idle do cliente ou proxy intermediário | Medir primeiro byte e intervalos; verificar limites idle do proxy |
| Há status HTTP e corpo de erro | Gateway ou upstream | Guardar status, corpo e request ID; seguir o contrato de erro do provedor |
httpx.PoolTimeout | Pool do cliente | Medir concorrência e ocupação; mudar limites só com saturação confirmada |
| Cancelamento após o mesmo tempo total | Aplicação, job runner ou reverse proxy | Identificar o dono do deadline e comparar com os timers inferiores |
Siga esta ordem: preserve o sinal, reproduza no mesmo host ou container, verifique cada proxy intermediário e depois avalie gateway ou upstream. Mantenha modelo, prompt, rede, endpoint e proxy constantes; altere apenas uma variável por teste.
O HTTPX documenta timeouts separados para connect, read, write e pool. Valores concretos não são universais: devem vir das medições, das pausas esperadas entre chunks e do deadline total.
Quando mudar timeout, saída ou retry
- Mude connect timeout somente se DNS/TCP/TLS estiver comprovadamente lento.
- Mude read ou idle timeout se a conexão existe e um limite intermediário confirmado expira entre chunks.
- Aumente o deadline total apenas se a operação puder durar mais e as camadas inferiores funcionarem.
- Reduza ou divida a saída quando apenas o teste longo controlado falhar; não assuma isso sem medições.
- Trate
429e estouro de contexto separadamente: eles não são connect timeout.
Retry seguro sem duplicar uma operação desconhecida
Após o envio, um timeout é primeiro um resultado desconhecido. Um task ID local ajuda a correlacionar logs, mas não impede uma segunda operação no servidor. Repita automaticamente somente se houver idempotência ou consulta de status documentada e evidência externa de que a primeira solicitação não foi aceita.
Checklist mínimo:
- Guardar request ID, status/corpo, timestamps e chunks recebidos.
- Antes de repetir uma ação não idempotente, verificar o resultado real.
- Não reenviar automaticamente um stream parcial; isso pode criar outra geração e uso adicional.
- Limitar tentativas e deadline total; somar retries do SDK, proxy e aplicação.
- Capturar também erros durante a iteração SSE, não apenas na criação do objeto response.
Dois testes confirmam a correção
- Solicitação curta: peça uma resposta pequena e registre status, tempo até o primeiro byte, duração, request ID e conclusão do stream. Se falhar, verifique conexão, autenticação e endpoint.
- Solicitação longa controlada: depois do sucesso anterior, aumente apenas a saída esperada ou restaure a carga original. Mantenha modelo, endpoint, rede e proxy. Se só este teste falhar, compare read/idle timeout, deadline total e limites intermediários.
A correção fica confirmada quando o teste curto e uma repetição do cenário original terminam com o resultado esperado e sem duplicatas inexplicáveis. Se a solicitação chegou ao BetterToken, compare no Dashboard horário, modelo, status e uso de Tokens e depois verifique o contrato do endpoint.
