Tempos limite de requisições da Claude API e “o streaming é altamente recomendado”

Geralmente há três tempos limite entre você e o modelo — o do seu SDK, o de um intermediário e a própria regra do provedor para chamadas longas sem streaming — e o menor deles vence. Aumentar apenas o do SDK é o motivo de isso continuar acontecendo depois que você achou que havia corrigido o problema.

O erro

two shapes

# Rejected before generating, for a long non-streaming request:
{"type":"error","error":{"type":"invalid_request_error",
 "message":"Streaming is strongly recommended for operations that may take
 longer than 10 minutes."}}

# Or the client-side companion, with no response at all:
APITimeoutError: Request timed out.

Causas e soluções em resumo

Causa	Solução
Uma geração longa sem streaming	Use streaming. Espera-se que conclusões longas sejam transmitidas em streaming, não aguardadas.
O tempo limite do cliente do SDK é menor que o da geração	Aumente-o — mas aumente também o limite do intermediário, ou nada mudará.
Um proxy, balanceador de carga ou função serverless limitando a solicitação	Encontre o limite mais curto na cadeia; é esse que você está atingindo.
Conexão aceita, mas nunca respondeu	É um travamento, não uma resposta lenta. Limite separadamente o tempo até o primeiro byte.

Use streaming para qualquer coisa que possa ultrapassar alguns minutos

Além de evitar o limite, o streaming fornece um sinal de atividade: a chegada de tokens significa que o modelo está trabalhando, então um travamento se torna distinguível de um progresso lento. Com uma única chamada bloqueante, os dois parecem idênticos até o disparo do tempo limite.

Aumente todos os tempos limite na cadeia, não apenas o do SDK

As pessoas quase sempre alteram o cliente e param por aí. Se um proxy reverso ou uma plataforma serverless limitar a solicitação abaixo do novo tempo limite do cliente, o limite ainda vencerá e o sintoma não mudará.

client.py

from anthropic import Anthropic

# Client timeout is only one of the limits in play.
client = Anthropic(api_key=KEY, timeout=600.0)

with client.messages.stream(
    model="claude-sonnet-5",
    max_tokens=8192,
    messages=[{"role": "user", "content": prompt}],
) as stream:
    for text in stream.text_stream:
        print(text, end="", flush=True)

Limite o tempo até o primeiro byte separadamente da duração total

São duas falhas diferentes que exigem dois remédios diferentes. Um prazo curto para o primeiro byte detecta rapidamente uma conexão morta; um prazo total generoso permite que uma geração realmente longa termine. Um único tempo limite combinado não consegue fazer as duas coisas.

Torne as tentativas seguras antes de adicioná-las

Uma solicitação que atingiu o tempo limite do seu lado pode ter sido concluída no upstream. Se o trabalho tiver efeitos colaterais ou se você for cobrado por chamada, adicione idempotência na sua camada antes de incluir um loop de novas tentativas.

Se você estiver chamando pela Kunavo

A Kunavo publica seus próprios números, em vez de deixar você descobri-los: ela espera no máximo 240 segundos pelos cabeçalhos de resposta do upstream, e uma resposta sem streaming normalmente envia seus cabeçalhos somente quando está concluída; portanto, uma chamada sem streaming que precise de mais tempo que isso não será concluída pelo gateway — use streaming. O limite de 240 segundos se aplica apenas ao tempo até os cabeçalhos e é liberado assim que eles chegam, portanto nunca trunca um stream longo; nada mais no gateway limita a duração de um stream. O que encerra um stream é o silêncio: 300 segundos sem um byte do upstream ou 600 segundos sem um byte na conexão com você. As rotas síncronas de imagem, vídeo e música mantêm a conexão aberta por até 540 segundos enquanto uma renderização termina, dentro dessa janela de 600 segundos, porque as renderizações legitimamente levam minutos. Uma solicitação que atinge o tempo limite antes dos cabeçalhos é contabilizada como falha de canal, é repetida no próximo canal do modelo quando houver um configurado e é registrada com custo zero.

Perguntas frequentes

Uma solicitação que atingiu o tempo limite é cobrada?

Na Kunavo, não — solicitações com falha são registradas com custo zero. A cobrança direta por um provedor depende de a geração ter ocorrido de fato.

Por que o streaming evita o limite?

A resposta começa em segundos e a conexão permanece ocupada, portanto nenhum período isolado de silêncio é longo o suficiente para acionar um tempo limite.

Qual deve ser o tempo limite do meu cliente?

Mais longo que sua pior geração realista, combinado com um prazo curto separado para o primeiro byte. Um único tempo limite combinado e longo transforma todo travamento em uma espera de vários minutos.

Guias relacionados

Mais detalhes sobre o significado dos erros estão em referência de erros; obter uma chave leva um minuto por meio de cadastro e da guia de autenticação.

Tempos limite de requisições da Claude API e “o streaming é altamente recomendado” — a regra dos 10 minutos