Resposta curta: não mude de Claude para GPT a cada requisição com falha. Um 401 significa que a autenticação deve ser corrigida, e um 404 relacionado ao caminho significa que a URL ou o endpoint devem ser corrigidos. Um 429 ou um 5xx temporário podem ser tentados novamente com backoff; se as tentativas limitadas ainda falharem, um modelo compatível pode assumir como fallback.
Há uma exceção importante: uma resposta 500 com error.code: invalid_request ainda é um problema de requisição. Repetir a tentativa — ou enviar o mesmo payload quebrado para outro modelo — apenas oculta o bug.
Este artigo foi verificado em 20 de agosto de 2026 com base na documentação da CometAPI sobre erros, retentativas, URL base, limites de taxa e fallback de modelos. Ele trata apenas da classificação de erros. Para design de rotas, credenciais de provedores e failover em múltiplas camadas, use o tutorial completo de fallback de modelos e o guia técnico de fallback.
Comece com a decisão de Retentar ou Falhar
| Status | Geralmente significa | Retentar? | Fallback? | Primeira ação |
|---|---|---|---|---|
| 401 | Chave ausente ou inválida | Não | Não | Corrigir o token Bearer |
| 404 | Caminho ou endpoint incorreto | Não | Não | Verificar URL base e rota |
| 429 | Limite de taxa ou saturação | Sim | Após tentativas limitadas | Fazer backoff com jitter |
| 500 + invalid_request | Requisição malformada | Não | Não | Corrigir o payload |
| 500/503/504/524 | Falha temporária da plataforma/provedor | Sim | Após tentativas limitadas | Manter o ID da solicitação |
A questão prática não é “O Claude falhou?”. É “Um modelo diferente poderia ter sucesso sem alterar a parte inválida desta requisição?”. Erros de autenticação e de caminho afetam a conexão em si, portanto mudar o modelo não os resolve. Falhas temporárias de capacidade e de servidor podem ser específicas da rota, então um fallback pode ajudar.
Leia o erro antes de trocar de modelo
Use o status HTTP junto com error.code e error.message. Muitas falhas da CometAPI usam um envelope como este:
{
"error": {
"message": "human-readable detail and request id",
"type": "comet_api_error",
"param": "problematic_parameter_or_empty",
"code": "error_code_or_empty"
}
}
Não classifique apenas pelo primeiro dígito do código de status. Um 500 ainda pode conter invalid_request, enquanto um caminho errado da CometAPI pode retornar um redirecionamento ou HTML em vez de um 404 JSON limpo.
401 Unauthorized: pare e corrija a autenticação
Um 401 geralmente significa que a chave da API está ausente, malformada, expirada ou carregada do ambiente errado. O cabeçalho deve ser:
Authorization: Bearer $COMETAPI_KEY
Não retente e não troque de modelo. Ambas as rotas usarão a mesma autenticação quebrada. Verifique se o serviço em produção carregou um segredo antigo, se espaços em branco foram adicionados à chave e se a requisição está chegando ao ambiente pretendido. Faça a rotação ou recarregue a chave apenas por meio do seu processo de gestão de segredos.
404 Not Found: corrija a URL antes do fallback
Para requisições compatíveis com OpenAI, use exatamente esta URL base:
https://api.cometapi.com/v1
A ausência de /v1, um segmento de caminho duplicado ou o endpoint errado podem produzir 404, um redirecionamento, uma resposta em HTML ou um erro de análise no SDK. Desative o seguimento automático de redirecionamentos durante a depuração e confirme o caminho final da requisição com a referência da API.
Se a resposta disser explicitamente que um modelo está indisponível ou não foi encontrado, verifique o ID do modelo na API de Modelos da CometAPI. Não trate todo 404 como indisponibilidade de modelo. Adicione um fallback específico para modelo apenas após capturar e testar exatamente esse sinal.
429 Too Many Requests: faça backoff antes de falhar para outra rota
Um 429 é retentável. Use backoff exponencial com jitter, reduza a simultaneidade em rajadas e meça qual rota está saturando. Uma retentativa imediata por cada worker pode transformar uma pequena limitação de taxa em um pico de tráfego maior.
Após um número pequeno e limitado de tentativas, o fallback pode ser apropriado quando o próximo modelo suporta a mesma entrada, contrato de saída e capacidades necessárias. O fallback não é gratuito: ele adiciona latência e pode alterar custo ou comportamento, então registre com que frequência é usado.
Erros 5xx: verifique o código e só então retente
500, 503, 504 e 524 geralmente representam falhas da plataforma, do provedor ou de timeout. Mantenha o ID da requisição, endpoint, modelo e timestamp, depois retente com backoff. Se a mesma falha transitória persistir após o orçamento de retentativas, mude para a próxima rota compatível.
Mas inspecione o corpo primeiro. Quando um 500 contiver error.code: invalid_request ou invalid_request_error, corrija o payload e só retente depois de modificá-lo. Causas comuns incluem um campo messages ausente ou um parâmetro específico de provedor que o endpoint selecionado não aceita.
Use uma política simples no código
Este exemplo em Python mantém retentativas e fallback no aplicativo. Ele usa uma única chave da CometAPI, a URL base compatível com OpenAI e variáveis de ambiente para os IDs de modelo atuais de Claude e GPT. Ele tenta novamente apenas falhas transitórias e, depois que o orçamento de retentativas se esgota, troca de modelo.
import os, random, time
from openai import APIError, OpenAI
client = OpenAI(
api_key=os.environ["COMETAPI_KEY"],
base_url="https://api.cometapi.com/v1",
max_retries=0,
)
MODELS = [os.environ["CLAUDE_MODEL"], os.environ["GPT_MODEL"]]
RETRYABLE = {429, 500, 503, 504, 524}
def complete(messages):
for model in MODELS:
for attempt in range(3):
try:
response = client.chat.completions.create(model=model, messages=messages)
return response.choices[0].message.content
except APIError as error:
status = getattr(error, "status_code", None)
code = getattr(error, "code", None)
if status in {401, 404} or code in {
"invalid_request", "invalid_request_error"
}:
raise
if status not in RETRYABLE:
raise
if attempt < 2:
time.sleep(2**attempt + random.random())
continue
break
raise RuntimeError("No configured route completed.")
print(complete([{"role": "user", "content": "Summarize this ticket."}]))
As retentativas automáticas do SDK estão desativadas para que o aplicativo controle o orçamento total de retentativas e fallback. Sem esse controle, retentativas do SDK somadas às do aplicativo podem multiplicar chamadas e atrasar a resposta final.
Teste a política sem adivinhar
| Sinal simulado | Resultado esperado | O que não deve acontecer |
|---|---|---|
| 401 | Falhar imediatamente | Sem retentativas e sem chamada ao GPT |
| 404 | Falhar imediatamente | Sem fallback ocultando um caminho ruim |
| 429 | Backoff, depois fallback | Sem tempestade de retentativas imediatas |
| 500 + invalid_request | Falhar imediatamente | Sem duplicar a requisição quebrada |
| 503/504/524 | Backoff, depois fallback | Sem cadeia ilimitada de rotas |
Estes são testes de política, não afirmações sobre a confiabilidade do provedor em produção. Em staging, injete o status e o corpo do erro no classificador, verifique o número e a ordem das chamadas e confirme que seu erro final ainda inclui o contexto da requisição original.
Quando o fallback de Claude para GPT é realmente seguro
Trocar de família de modelos é seguro apenas quando ambas as rotas conseguem satisfazer o mesmo contrato do aplicativo. Normalize os campos de requisição e resposta, teste a saída estruturada ou o comportamento de ferramentas em ambos os modelos e verifique qualquer capacidade exigida de imagem, documento, contexto ou raciocínio antes de habilitar a rota.
O fallback também deve respeitar efeitos colaterais. Se a primeira rota já acionou uma ferramenta, gravou dados ou transmitiu uma resposta parcial, repetir cegamente a mesma requisição pode duplicar ações ou confundir o usuário. Retome a partir de um checkpoint ou retorne uma falha controlada.
Verificações em produção que mantêm as retentativas limitadas
- Defina um orçamento total de latência único. Conte toda retentativa e fallback dentro do mesmo prazo.
- Limite as retentativas. Use backoff com jitter e pare após um limite pequeno configurado.
- Controle a simultaneidade. Reduza rajadas antes que as requisições saiam do aplicativo.
- Adicione um circuit breaker. Interrompa temporariamente chamadas para uma rota que falha repetidamente.
- Registre as decisões. Capture status, código de erro, ID da requisição, modelo, tentativa, atraso e motivo do fallback, sem armazenar segredos.
- Acompanhe a taxa de fallback. Um aumento sustentado é um sinal operacional, não uma métrica normal de sucesso.
Perguntas frequentes
Um 401 deve acionar fallback de modelo?
Não. Corrija ou recarregue a chave da API. Um modelo diferente chamado com a mesma credencial inválida falhará pelo mesmo motivo.
Um 404 deve acionar fallback?
Não por padrão. Primeiro corrija a URL base ou o endpoint. Apenas um sinal de indisponibilidade de modelo, verificado separadamente, deve entrar no classificador de fallback.
Quantas vezes devo retentar um 429?
Use um limite pequeno definido pela aplicação que caiba no orçamento de latência para o usuário. Faça backoff com jitter e reduza a simultaneidade; não retente imediatamente nem indefinidamente.
Todos os erros 5xx são retentáveis?
Não. Respostas temporárias 500, 503, 504 e 524 são candidatas a retentativa, mas 500 com invalid_request deve falhar de forma rígida até que o payload seja corrigido.
Claude e GPT podem usar a mesma requisição sem alterações?
Apenas para os campos compartilhados que seu aplicativo testou. Parâmetros específicos de provedor, formatos de ferramentas, saídas estruturadas e entradas multimodais podem exigir adaptadores. Mudar apenas o ID do modelo não prova compatibilidade.
Onde está a implementação completa de fallback?
Veja Como construir estratégias robustas de fallback de modelos para a arquitetura mais ampla e o guia de fallback de modelos da CometAPI para detalhes de implementação.
Faça do classificador de erros o porteiro
O fallback automático é útil quando é estreito e observável. Deixe erros de autenticação, caminho e requisição malformada falharem de forma ruidosa. Retente limites de taxa e falhas temporárias de servidor com backoff, depois mude para uma rota compatível apenas após esgotar o orçamento de retentativas. Essa política transforma o fallback em um controle de confiabilidade, e não em uma forma de ocultar bugs de configuração.