Timeouts, limites de taxa e novas tentativas

Documentação mantida por 1ZheAI. Fontes e correções.

Encontrou um erro? Contate o suporte com o endereço da página e uma descrição. Não envie chaves de API ou credenciais de conta.

Primeiro corrija erros de configuração, depois lide com falhas temporárias. Limite o número de novas tentativas, a concorrência e o tempo total de espera em conjunto, para evitar reenviar a mesma requisição com falha muitas vezes em pouco tempo.

Quais casos devem ser retentados

Caso	Recomendação
400 / 401 / 403 / 404	Corrija a requisição, permissões ou modelo primeiro; não repita automaticamente a requisição original
429	Verifique a mensagem da resposta; quando houver Retry-After, siga o tempo de espera indicado e reduza a concorrência
500 / 502 / 503 / 504 / 529	Novas tentativas limitadas são permitidas; em caso de falha contínua, pare e informe o ID da requisição
Falha de conexão	Verifique DNS, proxy e rede, e faça novas tentativas limitadas dentro do tempo permitido pela tarefa
Timeout ou interrupção do fluxo após o envio da requisição	O resultado pode ser incerto; verifique os logs primeiro; não assuma que o upstream ainda não processou

O escopo de novas tentativas das bibliotecas de cliente pode não ser exatamente igual à tabela acima. Em qual camada você usa novas tentativas, defina a política explicitamente nessa camada.

Use primeiro as novas tentativas embutidas do SDK

As unidades de timeout de Python e Node.js são diferentes: Python usa segundos, Node.js usa milissegundos. O exemplo abaixo define um timeout de 120 segundos e até 2 novas tentativas automáticas; na primeira integração, para depuração, pode-se alterar para 0.

Python

Python

import os
from openai import OpenAI

client = OpenAI(
    api_key=os.environ["ONEZHE_API_KEY"],
    base_url="https://1zheai.com/v1",
    timeout=120.0,
    max_retries=2,
)

Node.js

Node.js

import OpenAI from "openai";

const client = new OpenAI({
  apiKey: process.env.ONEZHE_API_KEY,
  baseURL: "https://1zheai.com/v1",
  timeout: 120_000,
  maxRetries: 2,
});

A configuração de timeout não é o limite total de duração de toda a tarefa de negócio: novas tentativas e esperas aumentam a duração total. Se a camada externa também reexecutar a tarefa, defina separadamente um prazo total e um mecanismo de cancelamento.

Ao implementar novas tentativas você mesmo

Desative as novas tentativas automáticas do SDK para evitar sobreposição. Use intervalos de espera crescentes com jitter aleatório; limite explicitamente o número de tentativas, a espera máxima e a fila de concorrência. Ao interpretar Retry-After, observe que pode ser tanto um número de segundos quanto uma data HTTP.

Se parte do resultado em streaming já foi exibida ao usuário, não faça replay automático do início e não anexe ao texto antigo. Mantenha o estado “incompleto” e deixe o usuário decidir se deseja gerar novamente ou continuar.

Tarefas de geração de imagens, execução de ferramentas e outras que possam produzir resultados externos exigem atenção especial quanto a envios duplicados. Não se pode assumir que definir um ID de requisição arbitrário fará o servidor deduplicar automaticamente.

Registre informações suficientes para depuração

Registre horário, endpoint, modelo, código de status, duração, número da tentativa e o ID da requisição retornado pelo servidor. Evite registrar cabeçalhos de autenticação e prompts privados completos. Use essas informações para comparar com os logs de chamada.

As configurações do SDK estão documentadas em OpenAI Python SDK e Node SDK. Para erros específicos, consulte códigos de erro e depuração.