Erros

Todos os códigos de status que o gateway retorna, suas causas reais e como resolver cada um.

Ver como Markdown Perguntar ao ChatGPT Perguntar no Claude

Os erros retornam JSON com um type e uma descrição legível message. Os códigos de status seguem as convenções da Anthropic e da OpenAI.

{"type": "error", "error": {"type": "authentication_error", "message": "invalid api key"}}

Códigos de status

Código	Significado	Causa real mais comum	Correção
`400`	Requisição inválida	Ausência de `max_tokens` em Messages, ou um `messages` array	Verifique o corpo de acordo com Messages
`401`	Não autenticado	Chave enviada no cabeçalho errado para o formato	`x-api-key` para Messages, Bearer para Chat Completions
`402`	Pagamento necessário	Saldo esgotado ou plano expirado	Adicionar créditos ou comprar um plano
`403`	Acesso proibido	Chave revogada ou modelo não habilitado para a conta	Crie uma nova chave; verifique `/v1/models`
`404`	Não encontrado	Erro na URL base — geralmente por duplicação ou ausência de `/v1`	Consulte URLs base
`429`	Limite de requisições atingido	Excesso de requisições simultâneas	Aumente exponencialmente o intervalo entre tentativas; consulte Limites de requisições
`500`	Erro de gateway	Falha interna inesperada	Tente novamente uma vez; se o problema persistir, entre em contato com o suporte e informe o ID da requisição
`529`	Provedor sobrecarregado	Capacidade do provedor, não da sua conta	Tente novamente com intervalos crescentes — geralmente se resolve em segundos

Tipos de erro

tipo	Significado
`invalid_request_error`	O corpo está malformado ou falta um campo obrigatório
`authentication_error`	Chave ausente, malformada ou revogada
`permission_error`	A chave é válida, mas não tem permissão para usar esse modelo
`not_found_error`	Caminho desconhecido ou ID de modelo desconhecido
`rate_limit_error`	Requisições limitadas
`api_error`	Falha interna
`overloaded_error`	Capacidade do provedor esgotada

Como repetir tentativas corretamente

Nova tentativa 429, 500, 502, 503 e 529. Nunca repita tentativas às cegas 400, 401, 402 ou 403 — a mesma requisição falha da mesma forma e, no caso de respostas parcialmente geradas, você pode pagar duas vezes.

import time, httpx

def call(body, key, tries=4):
    for i in range(tries):
        r = httpx.post(class="s">"https://aiprimetech.io/v1/messages", json=body, timeout=120,
                       headers={class="s">"x-api-key": key,
                                class="s">"anthropic-version": class="s">"2023-06-01"})
        if r.status_code in (429, 500, 502, 503, 529):
            time.sleep(2 ** i)          class=class="s">"c"># 1s, 2s, 4s, 8s
            continue
        r.raise_for_status()
        return r.json()
    raise RuntimeError(class="s">"upstream unavailable after retries")

Adicione uma variação aleatória ao tempo de espera em produção. Tentativas sincronizadas de muitos processos de trabalho transformam uma oscilação pontual em uma avalanche de requisições contra o mesmo provedor.

Limites de requisiçõesConcorrência e taxa de processamento Solução de problemasÍndice por sintoma