Gemini 503 “The model is overloaded” (UNAVAILABLE) — novas tentativas que funcionam e quando parar

“The model is overloaded” é o único erro do Gemini que não tem relação com você: o pool de atendimento desse modelo está sem capacidade no momento. Nada nas configurações do seu projeto pode impedir isso — o que você controla é a forma de lidar com a situação e o fallback escolhido quando ela não passa.

O erro

response (HTTP 503)

{
  "error": {
    "code": 503,
    "message": "The model is overloaded. Please try again later.",
    "status": "UNAVAILABLE"
  }
}

Causas e soluções em resumo

Causa	Solução
Pico de demanda no pool de atendimento desse modelo	Recuo exponencial com jitter; o pico geralmente passa em segundos ou poucos minutos.
Variantes de modelo de prévia / experimentais	Versões -exp e preview usam pools pequenos e ficam sobrecarregadas primeiro. Fixe o alias estável em produção.
Solicitações pesadas durante os horários de pico	Contextos enormes e limites máximos de saída têm maior probabilidade de serem descartados sob carga — reduza o que não for necessário e transmita a resposta em streaming.

Confirme que é 503 UNAVAILABLE, não 429

429 RESOURCE_EXHAUSTED é sua cota; 503 UNAVAILABLE é a capacidade do Google. A distinção determina tudo o que vem depois: erros de cota exigem alterações de faturamento ou limites, enquanto erros de capacidade exigem novas tentativas e fallbacks. Não depure as configurações do projeto por causa de um 503 — não há nada a encontrar nelas.

Tente novamente com recuo — mas dentro de um orçamento

503 é, por definição, passível de nova tentativa. Use o mesmo recuo exponencial com jitter usado para qualquer 429 (o trecho do nosso guia de 429 do Claude funciona sem alterações — ele já tenta novamente para status da classe 500), mas limite o tempo total de espera ao que o chamador consegue absorver; uma sobrecarga que persiste por cerca de 5 tentativas durante um minuto não vai passar rapidamente.

Quando as novas tentativas se esgotarem: mude o modelo, não o loop

Prepare uma cadeia de fallback antes de precisar dela: o alias estável se você estava em uma versão preview, gemini-2-5-flash se o 2.5 Pro estiver com problemas (ou vice-versa), ou um provedor completamente diferente para a solicitação que não pode falhar. Fallbacks transformam uma interrupção em uma redução de qualidade.

Se você estiver chamando pela Kunavo

Esse modo de falha explica por que o Kunavo tenta novamente dentro da solicitação: quando há mais de um canal upstream configurado para um modelo, uma tentativa malsucedida passa para o outro canal antes que você veja o erro — uma falha upstream temporária torna-se um sucesso mais lento em vez de um 503. Solicitações malsucedidas nunca são cobradas e, como uma única chave cobre Gemini, Claude e GPT, o fallback entre provedores na etapa 3 é uma alteração na string do modelo, não uma segunda integração. Considerando um modelo de fallback? As tarifas por token de toda a família Gemini, ao lado dos preços de lista do Google, estão na lista de preços da API do Gemini.

Perguntas frequentes

Solicitações que retornam 503 são cobradas?

Não — a solicitação é rejeitada antes da inferência, portanto o Google não a cobra; no Kunavo, solicitações malsucedidas também nunca são cobradas. O custo de um 503 é latência e novas tentativas, não tokens.

Quanto tempo duram as sobrecargas do Gemini?

Geralmente de segundos a poucos minutos; picos no dia do lançamento de um modelo novo podem durar mais. Por isso, a política sensata é fazer algumas tentativas com recuo e depois usar um modelo de fallback — não um loop de tentativas ilimitado.

A migração para um plano pago interrompe os 503?

Não. Planos pagos aumentam suas cotas (a família 429), mas 503 UNAVAILABLE é capacidade compartilhada de atendimento — tráfego gratuito e pago vê o erro quando um pool está saturado. Fallbacks são a mitigação, não o faturamento.

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.