Créditos da Claude API: por que sua aplicação para sem aviso?

Fala aí, beleza? A aplicação rodava lisa ontem, hoje toda chamada volta erro, e nenhum alerta apareceu antes disso

O consumo da Claude API roda em cima de um saldo pré-pago de créditos: você compra antes, e vai queimando conforme usa. Uso da API e do Workbench é cobrado assim, então sem saldo simplesmente não existe chamada

O detalhe cruel é que a conta acabando não chega como aviso de cobrança. Chega como erro de requisição no meio do teu código, parecendo bug de integração

Neste post a gente vai pelo caminho prático: diagnóstico (qual erro é qual), tratamento no código pra o usuário não comer a exceção crua, e prevenção pra você não descobrir o problema pelo relato de quem usa

Sintoma: erro 400 com "credit balance is too low"

Toda requisição volta HTTP 400 Bad Request. Não é uma rota, não é um prompt específico, é tudo

E aí começa a caça ao fantasma: você revisa o JSON, confere o nome do modelo, testa outro payload… e nada muda 🙃

Por que o 400 engana tanto?

Porque o corpo da resposta vem assim:

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "Your credit balance is too low to access the Anthropic API. Please go to Plans & Billing to upgrade or purchase credits."
  }
}

Repare no invalid_request_error

Esse é o mesmo tipo de erro que aparece quando a requisição está malformada. Ou seja, a falta de saldo não ganha um código de cobrança dedicado nesse caso, ela se disfarça de erro de payload

Se você não ler a message, vai passar a tarde debugando código que está certo

Solução: conferir o saldo e comprar crédito

1. Abra o Console e vá em Settings > Billing, na página platform.claude.com/settings/billing. É ali que o saldo de créditos da organização aparece
2. Se o saldo estiver zerado, clique no botão Buy credits e informe o valor que quer comprar
3. Confirme a compra. Os créditos ficam disponíveis imediatamente depois dela

Um aviso honesto antes de você fechar o diagnóstico: ver saldo na tela ajuda, mas não encerra o caso sozinho. Existe relato de conta com saldo de créditos visível no Console recebendo credit_balance_too_low em toda requisição, e eu volto nesse ponto mais pra frente

O erro comum deste passo: olhar a assinatura do Claude.ai e achar que ela cobre a API. Não cobre, e daqui a pouco eu volto nesse ponto também

Como prevenir: auto-reload ligado

Na própria página de Billing existe a recarga automática (auto-reload), que você liga ou desliga

Você define um saldo mínimo da conta e o valor de recarga que entra quando esse mínimo é atingido. É o jeito mais barato de nunca mais viver isso

Tome cuidado com um detalhe: créditos de API comprados expiram um ano após a data da compra, e essa validade não pode ser estendida. Comprar um caminhão de crédito "pra nunca mais pensar nisso" tem prazo de validade

Sintoma: o retry automático e o fallback não resolvem esse erro

"Mas eu tenho retry configurado, tenho fallback pra outro provider, minha app não deveria cair"

Deveria, né? Só que não é assim que funciona aqui

Causa: erro de cobrança não é falha transitória

Os SDKs oficiais fazem retry automático apenas de falhas transitórias: erros de conexão, rate limit e 5xx. Isso com backoff exponencial, duas vezes por padrão, respeitando o header retry-after

Saldo insuficiente não entra nessa classe. E faz sentido: repetir a chamada não vai fazer crédito aparecer do nada 😅

Tem também o caso reportado no LiteLLM, em que o 400 de saldo baixo não aciona o fallback routing. A camada que você montou justamente pra segurar queda de provider deixa passar esse erro, porque ele não parece uma falha de infraestrutura

Solução e prevenção

Trate a falta de saldo como um caso explícito da sua aplicação, com caminho próprio

E não delegue esse cenário pra camada de roteamento. Ela cobre instabilidade, não cobre conta sem saldo

Sintoma: o usuário final recebe o erro cru da API

Aquela cena clássica: a mensagem em inglês sobre "credit balance" estampada na interface de quem só queria usar o teu produto

Além de feio, entrega pro usuário um problema que é teu

Causa: comparação de string em vez de tipo

Muito código trata erro de API assim: pega a exceção, procura um pedaço de texto na mensagem, decide o que fazer

Mensagem muda. Tipo não muda

A recomendação oficial é capturar as classes tipadas do SDK, do mais específico para o mais genérico. No SDK, 400 vira BadRequestError, 429 vira RateLimitError e 5xx vira InternalServerError. Todas estendem APIError / APIStatusError, e essa classe base expõe a propriedade de status

Solução: captura por classe, do específico ao genérico

import anthropic

client = anthropic.Anthropic()

try:
    resposta = client.messages.create(...)
except anthropic.BadRequestError:
    # 400: aqui mora o caso de saldo insuficiente
    # avisa o time e devolve mensagem amigavel pro usuario
    notificar_time("possivel falta de credito na Claude API")
    return mensagem_de_indisponibilidade()
except anthropic.RateLimitError:
    # 429: esse sim vale esperar e tentar de novo
    return enfileirar_novamente()
except anthropic.APIStatusError as erro:
    # qualquer outro status devolvido pela API
    registrar_log(erro)
    return mensagem_de_indisponibilidade()

Os nomes das classes mudam por linguagem, então não copie de cabeça de um SDK pro outro

O 404, por exemplo, é anthropic.NotFoundError em Python e Anthropic::Errors::NotFoundError em Ruby. Em Go a coisa é diferente: existe um único valor de erro, e você checa o StatusCode dele

O erro comum deste passo: inverter a ordem dos except e capturar a classe genérica primeiro, o que engole o caso específico e te deixa sem tratamento nenhum

Como prevenir

Duas saídas no mesmo lugar: mensagem de fallback pro usuário ("o serviço está indisponível agora") e alerta pro time quando o status indicar cobrança

O usuário não precisa saber do teu billing, mas alguém do time precisa saber AGORA

Sintoma: 402 billing_error e a confusão com a assinatura do Claude.ai

Existe um erro de cobrança que não é aquele 400 do saldo zerado

É o 402 billing_error, que indica problema de cobrança ou de dados de pagamento. A orientação oficial nesse caso é conferir os dados de pagamento no Console

A lista oficial de erros, pra você saber o que está olhando

A lista oficial de erros da Claude API tem esses dez códigos. Vale deixar essa tabela colada no teu handler, porque metade do diagnóstico é só saber em qual linha você caiu

Como prevenir: são dois sistemas de cobrança, não um

Aqui mora uma das confusões mais comuns

A cobrança da API no Console e a assinatura do Claude.ai são sistemas de cobrança separados, com mecânicas e limites diferentes. Crédito de um não banca o outro

Então "eu pago assinatura, minha API não deveria parar" não se sustenta. São contas diferentes, saldos diferentes, e o "credit balance" que aparece no erro é o da API

Sintoma: tem crédito, mas o uso pausou no meio do mês

Saldo na conta, tudo pago, e mesmo assim as chamadas param. Que raiva, né?

Duas causas prováveis aqui

Causa 1: o teto mensal do teu tier

Existem três tiers de uso: Start, Build e Scale, cada um com um teto mensal de gasto (há ainda um tier Custom, sem teto mensal, negociado com o time de contas)

Ao atingir o teto do tier, o uso da API pausa até o mês seguinte, a menos que você peça um limite maior

E se liga nisso: os tiers são atribuídos automaticamente pelo histórico de uso e pela situação da conta. Não existe depósito ou compra que promova a organização de tier, então despejar crédito na conta não resolve esse caso

Causa 2: um limite que você mesmo definiu

Dá pra definir um teto mensal de gasto e alertas de aproximação do limite no Console, em Settings > Billing, pelo botão Adjust limit (ou Set limit, se ainda não existir limite). Esse limite não pode ultrapassar o teto do tier

E cada workspace tem uma aba Spend limits, onde você limita o gasto mensal e configura notificação por e-mail ao atingir um valor. Sem configuração própria, o workspace herda o limite da organização

Ou seja: aquele limite conservador que alguém definiu há seis meses pode ser exatamente o que derrubou a aplicação hoje

E lembra do alerta lá do começo? Existe caso reportado de conta com saldo de créditos visível no Console recebendo credit_balance_too_low em toda requisição. Saldo visível nem sempre é garantia de requisição aceita, então não descarte a hipótese de cobrança só porque o número na tela está bonito

Solução e prevenção

Pedido de limite maior sai pelo Console, e fica disponível a partir de 50% de uso dos limites atuais. Ou seja, dá pra pedir antes de bater a parede

E configure a notificação por e-mail na aba de spend limits do workspace. É configuração de cinco minutos que compra sono tranquilo

Sintoma: você só descobre o problema pelo relato do usuário

Esse é o pior de todos: a app parou às 3 da manhã, e a primeira notificação foi um print no WhatsApp às 9

Causa: não existe endpoint público de saldo

Essa é a parte que costuma surpreender quem quer montar um painel: não existe endpoint público da API pra ler o saldo de créditos restante

A consulta a GET /v1/organizations/balance retorna 404, e a exposição do saldo segue como pedido de recurso em aberto. O saldo, hoje, mora no Console

Solução: monitorar consumo pela Usage and Cost Admin API

Saldo você não lê por API, mas consumo você lê

A Usage and Cost Admin API dá acesso programático a uso e custo históricos da organização, equivalente às páginas de Usage e Cost do Console. Os endpoints são:

• GET /v1/organizations/cost_report
• GET /v1/organizations/usage_report/messages

A chamada usa uma Admin API key, que é diferente da chave de API comum. Ela tem o formato sk-ant-admin... e é provisionada no Console apenas por membros com papel de admin

GET /v1/organizations/cost_report
x-api-key: sk-ant-admin...
anthropic-version: 2023-06-01

O erro comum deste passo: tentar autenticar com a chave comum da aplicação. Não vai rolar, é outra credencial

Dois detalhes operacionais que economizam teu tempo: o relatório de custo aceita apenas buckets diários (1d), então esqueça granularidade por hora ali. E os endpoints da Spend Limits API compartilham um limite único por organização de 60 requisições por minuto, com 429 no excedente. Se o teu job de monitoramento for guloso, ele mesmo vira o problema 😅

Já que a conversa é gasto: boa parte do custo que some do radar vem de chamada mal aproveitada, e aí vale revisar como aproveitar melhor o Claude Opus antes de simplesmente comprar mais crédito

Como prevenir: três camadas

• auto-reload ligado, com saldo mínimo e valor de recarga definidos
• alertas de aproximação do limite de gasto, no Console e no workspace
• monitoramento de custo diário pela Admin API, com o número indo pro mesmo painel onde teu time já olha

O que aprendi construindo aplicação que depende de API externa

Esse tipo de dor eu conheço de perto, e não é de hoje

No vídeo abaixo eu mostro um projeto de aplicação de clima em HTML, CSS e JavaScript consumindo a OpenWeather API. Fiquei no plano gratuito de propósito, porque os dados básicos já bastavam pro que eu queria construir

E a lição número um apareceu antes da primeira linha de integração: cadastro e geração da chave são etapas obrigatórias, e é justamente aí que boa parte de quem tenta o projeto desanima

Eu testei a chave isolada, direto na URL da API, antes de escrever o código do projeto. Resultado: 401

Se eu tivesse pulado esse teste, eu ia acusar o meu fetch de estar errado, quando o problema era a credencial recém-criada que ainda não respondia. Contornei usando outra chave que já tinha, e a resposta esperada apareceu na tela numa boa

Percebe o paralelo? O status estava dizendo tudo. Só que quem lê rápido demais culpa o código

Outra coisa que esse projeto deixa escancarada: a aplicação depende de vários serviços de terceiros ao mesmo tempo (clima, imagem de fundo, ícones, bandeiras). Se um deles não responde, a tela quebra na cara do usuário

Por isso eu já deixei previsto ali um estado de carregamento com ícone, pra dar retorno visual quando a resposta demora em conexão lenta, e um tratamento de erro pra cidade inexistente, exibindo mensagem de falha em vez de tela morta

É exatamente o mesmo raciocínio da Claude API sem saldo: a diferença entre "o serviço está indisponível agora, tente em instantes" e uma exceção crua vazando pro usuário é um bloco de tratamento de erro que você escreve uma vez

Conclusão

Falta de crédito não é bug, é falha operacional previsível. E ela tem três características que fazem toda a diferença no teu diagnóstico

Ela chega como 400 com invalid_request_error, disfarçada de erro de payload

Ela não é falha transitória, então retry automático e fallback routing não cobrem ela

E o saldo só existe no Console, porque não há endpoint público de balance pra você consultar

Próximo passo, hoje mesmo: abre platform.claude.com/settings/billing, confere o saldo, liga o auto-reload com saldo mínimo e valor de recarga, e depois volta no teu código pra revisar o bloco de tratamento de erro por classe tipada

São vinte minutos de trabalho que evitam aquela madrugada de debug atrás de um problema que nunca esteve no código 🙂

até o próximo post!