---
title: "Timeouts, limites de taxa e novas tentativas"
description: "Configure timeouts do SDK e novas tentativas limitadas, distinguindo erros retentáveis de erros de configuração, para evitar envios duplicados."
headingIds: {"Quais casos devem ser retentados":"section-1","Use primeiro as novas tentativas embutidas do SDK":"section-2","Ao implementar novas tentativas você mesmo":"section-3","Registre informações suficientes para depuração":"section-4"}
---

<aside className="docs-publication" data-pagefind-ignore>

Documentação mantida por [1ZheAI](https://1zheai.com/en/editorial/#publisher). [Fontes e correções](https://1zheai.com/en/editorial/).

Encontrou um erro? [Contate o suporte](mailto:support@1zheai.com) com o endereço da página e uma descrição. Não envie chaves de API ou credenciais de conta.

</aside>
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.

<CodeGroup>
```python title="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,
)
```
```javascript title="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,
});
```
</CodeGroup>

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](/pt/docs/usage-logs/).

As configurações do SDK estão documentadas em [OpenAI Python SDK](https://github.com/openai/openai-python#retries) e [Node SDK](https://github.com/openai/openai-node#retries). Para erros específicos, consulte [códigos de erro e depuração](/pt/docs/troubleshooting/).