Tratamento de erros e limites de taxa
Trate erros comuns da API, incluindo exceções de limite de taxa, erros de autenticação e tempos limite, usando lógica de novas tentativas e padrões de espera exponencial.
Tratamento de erros e limites de taxa é uma aula grátis de AI Engineering Academy no CoddyKit. Esta é a aula 4 de 4. Você pode ler a aula completa abaixo gratuitamente — depois pratica ao vivo no navegador com um editor de código integrado e um tutor de IA 24/7. Faz parte do caminho de aprendizado de AI Engineering Academy, e seu progresso é sincronizado entre a web e o app CoddyKit. O curso de AI Engineering Academy inclui 4 aulas no total.
Por que ocorrem erros de API
Muita coisa pode dar errado em uma chamada de API: sobrecarga, cota baixa, queda da rede ou uma requisição inválida. Tratar as chamadas como infalíveis garante um código frágil — conheça primeiro os tipos de erro.
Visão geral dos tipos de erro da OpenAI
O SDK gera exceções específicas, como RateLimitError e AuthenticationError. Vale a pena tentar novamente apenas os erros temporários, como limites de taxa e quedas de rede — os demais não se corrigirão sozinhos.
Capturando erros com Try-Except
Coloque cada chamada dentro de try-except e capture exceções específicas, não um except genérico. Dessa forma, você reage de maneira adequada a cada falha, em vez de ocultar erros. O código mostra como fazer isso.
import openai
client = openai.OpenAI()
try:
response = client.chat.completions.create(
model='gpt-4o-mini',
messages=[{'role': 'user', 'content': 'Hello!'}]
)
print(response.choices[0].message.content)
except openai.AuthenticationError as e:
print('Bad API key. Check OPENAI_API_KEY environment variable.')
raise # do not retry
except openai.RateLimitError as e:
print('Rate limited. Back off and retry.')
except openai.APIConnectionError as e:
print('Network error:', e)
except openai.APIStatusError as e:
print('Server error', e.status_code, e.message)Entendendo os limites de taxa
A OpenAI aplica dois limites de taxa ao mesmo tempo: requisições por minuto (RPM) e tokens por minuto (TPM). Um prompt enorme pode esgotar seu TPM em uma única requisição. Ambos retornam 429.
Espera exponencial: a estratégia certa para novas tentativas
Atingiu um limite de taxa? Aguarde e tente novamente usando espera exponencial: 1 s, 2 s, 4 s, dobrando a cada vez. Adicione um pouco de variação aleatória e um número máximo de tentativas para nunca entrar em um ciclo infinito. Veja o código.
import time
import random
import openai
client = openai.OpenAI()
def call_with_backoff(messages, max_retries=5):
for attempt in range(max_retries):
try:
return client.chat.completions.create(
model='gpt-4o-mini',
messages=messages
)
except openai.RateLimitError:
if attempt == max_retries - 1:
raise
wait = (2 ** attempt) + random.uniform(0, 1)
print(f'Rate limited. Waiting {wait:.1f}s (attempt {attempt+1})')
time.sleep(wait)
except (openai.APIConnectionError, openai.APIStatusError):
if attempt == max_retries - 1:
raise
time.sleep(2 ** attempt)Usando a biblioteca tenacity
Não implemente novas tentativas manualmente — a biblioteca tenacity faz isso de maneira organizada. Decore sua função com @retry e ela cuidará da espera exponencial, da variação aleatória e das condições para novas tentativas.
from tenacity import retry, wait_random_exponential, stop_after_attempt
import openai
client = openai.OpenAI()
@retry(
wait=wait_random_exponential(min=1, max=60),
stop=stop_after_attempt(6)
)
def completion_with_backoff(**kwargs):
return client.chat.completions.create(**kwargs)
response = completion_with_backoff(
model='gpt-4o-mini',
messages=[{'role': 'user', 'content': 'Tell me a joke.'}]
)
print(response.choices[0].message.content)Configuração do tempo limite
Uma requisição travada pode congelar seu aplicativo para sempre, portanto sempre defina um tempo limite. O SDK aceita um tempo limite em segundos, no cliente ou por chamada. Escolha um valor adequado ao tamanho esperado da resposta.
import openai
# Set a default timeout for all requests from this client
client = openai.OpenAI(timeout=30.0)
# Or override per request
try:
response = client.chat.completions.create(
model='gpt-4o-mini',
messages=[{'role': 'user', 'content': 'Summarize the French Revolution.'}],
timeout=60.0
)
except openai.APITimeoutError:
print('Request timed out. Try a shorter prompt or increase timeout.')Tratando erros de autenticação
Um AuthenticationError (401) significa que sua chave está incorreta, expirada ou revogada — tentar novamente nunca ajudará. Registre o erro, envie um alerta e falhe rapidamente, em vez de consumir seu limite de tentativas.
import os
import openai
api_key = os.environ.get('OPENAI_API_KEY')
if not api_key:
raise EnvironmentError(
'OPENAI_API_KEY not set. Export it before running.'
)
client = openai.OpenAI(api_key=api_key)
try:
response = client.chat.completions.create(
model='gpt-4o-mini',
messages=[{'role': 'user', 'content': 'Hello'}]
)
except openai.AuthenticationError:
# Do NOT retry - the key itself is invalid
raise RuntimeError('Invalid API key. Check OPENAI_API_KEY.')Cota versus limites de taxa
Ambos se parecem com RateLimitError, mas são diferentes: os limites de taxa restringem o uso por minuto e são redefinidos automaticamente, enquanto os limites de cota são tetos de gastos que exigem mais créditos.
Registrando erros para depuração
Em produção, registre todos os erros com contexto: o tipo, o modelo, os parâmetros, a contagem de tokens, o horário e o ID da requisição. Esse ID é exatamente o que o suporte da OpenAI precisa. Veja o código.
import logging
import openai
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)
client = openai.OpenAI()
def safe_completion(model, messages):
try:
response = client.chat.completions.create(
model=model, messages=messages
)
return response
except openai.RateLimitError as e:
logger.warning(
'Rate limit hit',
extra={'model': model, 'error': str(e)}
)
raise
except openai.APIStatusError as e:
logger.error(
'API server error',
extra={
'status_code': e.status_code,
'request_id': e.request_id,
'model': model
}
)
raiseTratamento de erros em aplicativos de produção
Uma estratégia sólida para produção: falhe rapidamente diante de erros irrecuperáveis, tente novamente os erros temporários com espera exponencial e ofereça alternativas adequadas. Nunca permita que um erro de API derrube todo o seu servidor.
Verificação rápida
Teste sua compreensão dos conceitos de Engenharia de IA desta lição.
Recapitulação da lição
Você aprendeu a lidar com falhas: a OpenAI gera exceções específicas, os limites de taxa exigem espera exponencial com variação aleatória e os erros de autenticação devem falhar rapidamente. A seguir: escrevendo prompts poderosos.
Aprenda Python com um tutor de IA — grátis
Escreva e execute código real no seu navegador, obtenha ajuda instantânea de um tutor de IA 24/7 e continue de onde parou na web ou no app.
- Cursos
- 30
- Aulas
- 120
Perguntas Frequentes
A aula “Tratamento de erros e limites de taxa” é grátis?
Sim — o texto completo de “Tratamento de erros e limites de taxa” é grátis para ler aqui na web. Para praticá-la interativamente (um editor de código integrado e um tutor de IA 24/7) e desbloquear o restante do curso de AI Engineering Academy, atualize para CoddyKit PRO. O curso de AI Engineering Academy inclui 4 aulas no total.
O que vou aprender em “Tratamento de erros e limites de taxa”?
Trate erros comuns da API, incluindo exceções de limite de taxa, erros de autenticação e tempos limite, usando lógica de novas tentativas e padrões de espera exponencial. Você pratica AI Engineering Academy com código prático que executa diretamente no navegador, e um tutor de IA 24/7 responde suas dúvidas enquanto trabalha na aula.
Preciso ter experiência prévia para começar AI Engineering Academy?
Nenhuma experiência prévia é necessária. AI Engineering Academy no CoddyKit é estruturado para alunos iniciantes até avançados, então você pode começar aqui ou desde o início e aprender no seu ritmo. Esta é a aula 4 de 4.
Quanto tempo leva a aula “Tratamento de erros e limites de taxa”?
A maioria das aulas CoddyKit leva cerca de 5–10 minutos. Cada uma é compacta e interativa, então você faz progresso constante e retoma exatamente de onde parou entre web e app.
Posso escrever e executar código nesta aula de AI Engineering Academy?
Sim. Cada aula de AI Engineering Academy inclui um editor de código integrado, então você escreve e executa código real direto no navegador e recebe feedback de IA instantaneamente — nenhuma configuração local necessária.
Todas as aulas deste curso
- Configurando seu ambiente Python
- O endpoint de conclusões de conversa
- Controlando o comportamento do modelo com parâmetros
- Tratamento de erros e limites de taxa