Skip to Content
DocumentaçãoGuiasTratamento de erros

Tratamento de erros

Este guia descreve o formato de resposta de erro da API OfoxAI, cenários de erro comuns e estratégias de tratamento recomendadas.

Formato da resposta de erro

Todas as respostas de erro seguem um formato JSON padronizado:

{
  "error": {
    "code": "invalid_api_key",
    "message": "A API Key fornecida é inválida. Verifique e tente novamente.",
    "type": "authentication_error"
  }
}

Códigos de status HTTP

CódigoTipoDescriçãoDeve repetir?
400invalid_request_errorParâmetros da requisição incorretosNão — corrigir parâmetros
401authentication_errorAPI Key inválida ou ausenteNão — verificar API Key
403permission_errorPermissões insuficientesNão — verificar permissões da conta
404not_found_errorModelo ou recurso não encontradoNão — verificar ID do modelo
429rate_limit_errorLimite de taxa atingidoSim — aguardar e repetir
500internal_errorErro interno do servidorSim — tentar novamente
502upstream_errorErro no provedor de modelo upstreamSim — trocar modelo ou repetir
503service_unavailableServiço temporariamente indisponívelSim — tentar novamente

Erros comuns e soluções

401 — API Key inválida

{"error": {"code": "invalid_api_key", "message": "The API key provided is invalid."}}

Solução:

  • Verifique se o API Key foi copiado corretamente (com o prefixo sk-)
  • Confirme que o Key não expirou ou foi desativado
  • Verifique se a variável de ambiente está carregada corretamente

429 — Limite de taxa

{"error": {"code": "rate_limit_exceeded", "message": "Rate limit reached. Please retry after 1s."}}

Solução:

  • Verifique o header de resposta x-ratelimit-reset-requests
  • Implemente backoff exponencial
  • Para cotas mais altas, entre em contato com o suporte

502 — Erro upstream

{"error": {"code": "upstream_error", "message": "The upstream provider returned an error."}}

Solução:

  • Use o failover para trocar automaticamente para um modelo alternativo
  • Tente novamente mais tarde
  • Verifique a página de status do provedor do modelo

Estratégia de retry

Recomenda-se usar backoff exponencial:

retry.py
import time
import random
from openai import OpenAI, APIError, RateLimitError, APIConnectionError
 
client = OpenAI(
    base_url="https://api.ofox.ai/v1",
    api_key="<Sua OFOXAI_API_KEY>"
)
 
def chat_with_retry(max_retries=5, **kwargs):
    """Wrapper de retry com backoff exponencial"""
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(**kwargs)
 
        except RateLimitError:
            # 429: Aguardar e repetir
            wait = (2 ** attempt) + random.uniform(0, 1)
            print(f"Limite de taxa atingido, aguardando {wait:.1f}s...")
            time.sleep(wait)
 
        except APIConnectionError:
            # Erro de rede: Aguardar brevemente e repetir
            wait = 2 ** attempt
            print(f"Erro de conexão, aguardando {wait}s...")
            time.sleep(wait)
 
        except APIError as e:
            if e.status_code and e.status_code >= 500:
                # 5xx: Erro do servidor, repetir
                wait = 2 ** attempt
                time.sleep(wait)
            else:
                # 4xx: Erro do cliente, não repetir
                raise
 
    raise Exception(f"Falha após {max_retries} tentativas")
 
# Uso
response = chat_with_retry(
    model="openai/gpt-4o",
    messages=[{"role": "user", "content": "Olá"}]
)

Configuração de timeout

Recomenda-se configurar um timeout adequado para as chamadas da API:

# Python OpenAI SDK
client = OpenAI(
    base_url="https://api.ofox.ai/v1",
    api_key="<Sua OFOXAI_API_KEY>",
    timeout=60.0,  # Timeout de 60 segundos
    max_retries=3  # Retry integrado ao SDK
)
// TypeScript OpenAI SDK
const client = new OpenAI({
  baseURL: 'https://api.ofox.ai/v1',
  apiKey: '<Sua OFOXAI_API_KEY>',
  timeout: 60000,  // Timeout de 60 segundos
  maxRetries: 3    // Retry integrado ao SDK
})

Para requisições em streaming, recomenda-se um timeout mais longo (120 a 300 segundos), pois o modelo pode precisar de mais tempo para gerar o conteúdo completo.

Boas práticas

  1. Diferencie erros que podem e não podem ser repetidos — 4xx geralmente requerem correção da requisição; 5xx podem ser repetidos
  2. Use backoff exponencial — Evite retries frequentes durante throttling
  3. Defina um número máximo de tentativas — Previna loops infinitos
  4. Registre logs de erro — Facilita a investigação de problemas
  5. Configure failover — Use o parâmetro provider.fallback do OfoxAI para troca automática de modelo
  6. Monitore a taxa de erros — Acompanhe as tendências de erro no painel
Last updated on
Saída estruturadaRoteamento de provedores