Claude API 500 api_error e 502 Bad Gateway — uma política de novas tentativas que realmente recupera

500 e 502 significam uma falha, não um limite. Isso faz deles a única classe de erros desta família que vale a pena repetir quase imediatamente — ao contrário de 429, que é seu próprio limite de taxa, e 529, que significa que o provedor está lotado. Repetir o erro errado entre os três transforma um pequeno incidente no seu incidente.

O erro

two shapes, same remedy

// Straight from the model provider (HTTP 500)
{
  "type": "error",
  "error": { "type": "api_error", "message": "Internal server error" }
}

// From a gateway or proxy in between (HTTP 502)
{
  "error": {
    "message": "Failed to reach upstream provider",
    "type": "upstream_error",
    "code": "upstream_error",
    "param": null
  }
}

Causas e soluções em resumo

Causa	Solução
Falha transitória do lado do provedor	Repita com backoff exponencial e jitter, limitado a ~5 tentativas.
Conexão aceita, mas nunca respondeu	É um travamento, não um erro. Limite o tempo até o primeiro byte separadamente da duração total.
Um intermediário retornando seu próprio 502	Não tem relação com o modelo. Verifique se o corpo tem o formato do provedor ou de um proxy.
Repetir cegamente durante um incidente real	Limite as tentativas e use backoff — caso contrário, suas novas tentativas se tornarão parte da indisponibilidade.

Separe 500 de 529 e 429 antes de escolher uma solução

429 é um limite de taxa que você está excedendo — diminua a velocidade. 529 significa que o provedor está na capacidade máxima — use backoff muito mais forte e longo. 500/502 é uma falha, geralmente breve e muitas vezes específica de uma única solicitação. Apenas o terceiro grupo merece novas tentativas rápidas, e tratar os três da mesma forma é o motivo pelo qual loops de tentativas tornam os incidentes piores.

Repita erros 5xx, nunca 4xx

Backoff exponencial com jitter, no máximo cinco tentativas. O mesmo auxiliar funciona para todos os provedores — um 400 ou 422 falhará da mesma forma na tentativa seguinte, portanto repeti-lo apenas consome latência para chegar ao mesmo erro.

backoff.py

import time, random
from openai import OpenAI, APIStatusError

client = OpenAI(base_url="https://api.kunavo.com/v1", api_key="sk-kn-...")

def with_backoff(fn, max_retries=5):
    for attempt in range(max_retries):
        try:
            return fn()
        except APIStatusError as e:
            if e.status_code not in (429, 500, 529):
                raise                      # don't retry auth/validation errors
            retry_after = e.response.headers.get("retry-after")
            delay = float(retry_after) if retry_after else min(2 ** attempt, 30)
            time.sleep(delay + random.uniform(0, 0.5))   # jitter avoids herds
    raise RuntimeError("retries exhausted")

resp = with_backoff(lambda: client.chat.completions.create(
    model="claude-sonnet-5",
    messages=[{"role": "user", "content": "ping"}],
    max_tokens=32,
))
print(resp.choices[0].message.content)

Limite o tempo até o primeiro byte separadamente da duração total

Um único tempo limite para toda a solicitação não consegue distinguir uma geração longa de uma conexão morta. Defina um prazo curto para o primeiro byte e um prazo generoso para o restante; assim, um travamento falha rapidamente, enquanto uma resposta genuinamente lenta é deixada prosseguir.

Registre o status e a latência de cada tentativa

Sem registros por tentativa, um incidente do provedor e seu próprio tempo limite parecem idênticos depois do fato. O código de status, a latência e o número da tentativa bastam para diferenciá-los na manhã seguinte.

Se você estiver chamando pela Kunavo

Em setembro de 2026, todos os modelos Claude na Kunavo são servidos por um único canal upstream, portanto um erro 5xx desse canal não é repetido dentro da solicitação: ele chega até você como um 502 com a mensagem “Upstream provider error” (tipado como api_error em /v1/messages), e a solicitação é registrada com custo zero. A nova tentativa dentro da solicitação da Kunavo só é executada para um modelo com um segundo canal configurado: um tempo limite, um 5xx, um 429 ou uma rejeição da própria chave upstream da Kunavo é então repetido nesse canal antes de chegar até você, em /v1/messages, /v1/responses e nos modelos Claude em /v1/chat/completions. Um stream é retido até que seu primeiro conteúdo chegue, portanto um erro dentro de um stream que ainda não começou também é repetido; depois que o conteúdo começa a fluir, uma falha no meio do stream fica sob sua responsabilidade. De qualquer forma, mantenha do seu lado a política de novas tentativas desta página. O roteamento por trás desse comportamento é descrito em nosso guia do gateway de IA.

Perguntas frequentes

Sou cobrado por uma solicitação que retorna 500?

Na Kunavo, não — solicitações com falha são registradas com custo zero. A cobrança direta por um provedor varia, mas geralmente um 5xx não é cobrado.

Repetir um 500 pode produzir duas conclusões?

Sim. Uma solicitação pode falhar depois que o modelo já gerou conteúdo. Se o trabalho tiver efeitos colaterais, torne-o idempotente na sua camada antes de adicionar novas tentativas.

Qual é a diferença em uma linha entre 500, 502 e 529?

500 significa que o provedor está falhando, 502 significa que algo à frente dele não conseguiu alcançá-lo e 529 significa que o provedor está na capacidade máxima — repita os dois primeiros em breve e o terceiro bem mais tarde.

Guias relacionados

Mais detalhes sobre o significado dos erros estão em referência de erros; obter uma chave leva um minuto por meio de cadastro e da guia de autenticação.