429 nas requisições seguintes dele até que um administrador aumente o limite, ou até que o limite seja redefinido, caso esteja acima de $0. Use limites de gastos para dar a cada desenvolvedor, grupo ou toda a organização um teto de gastos em uma credencial que todos compartilham.
Por padrão, um gateway de aplicativos Claude encaminha toda a inferência através de uma credencial upstream compartilhada, portanto a fatura do seu provedor atribui tudo a essa credencial, não a desenvolvedores individuais. No Amazon Bedrock, atribuição de custo AWS por desenvolvedor muda isso. Sem limites por desenvolvedor, uma frota de agentes descontrolada pode gastar todo o compromisso da organização. Limites de gastos são a visão por desenvolvedor do gateway e o disjuntor em cima dessa fatura compartilhada.
Defina um limite
Com o blocoadmin: configurado em gateway.yaml, o gateway fornece uma API de administrador em /v1/organizations/spend_limits e aplica limites em tempo real em cada solicitação de inferência. Os limites em si são definidos através dessa API, não em gateway.yaml; cada solicitação POST /v1/organizations/spend_limits cria ou substitui um limite de {scope, amount, period}. A API espelha as formas de transmissão dos endpoints de limites de gastos da API de Administrador pública da Anthropic, portanto um cliente HTTP escrito contra esse contrato pode direcionar o gateway alterando sua URL base.
Esta solicitação define um padrão em toda a organização de $500 por mês para cada desenvolvedor:
contractors:
Um limite de grupo ou organização é um padrão por assento que cada membro herda, não um pool compartilhado. Por período, o limite efetivo de um desenvolvedor é resolvido nesta ordem: uma substituição por usuário, depois a mais restritiva de seus limites de grupo, depois o padrão da organização, depois ilimitado.
admin.group_limit_mode: max inverte o desempate de múltiplos grupos para menos restritivo em vez disso.
Autentique-se na API de administrador
Envie um dos seguintes:- Um cabeçalho
x-api-keycorrespondendo a uma chave emadmin.write_keyspara acesso total, ouadmin.read_keyspara acesso somenteGET. Cada chave carrega umidque aparece no log de auditoria comoadmin-key:<id>, portanto dê ao Terraform, CI e cada automação a sua própria. - Um token de portador do gateway cujo
groupsclaim inclui um dosadmin.admin_groups. Este é acesso total e é auditado comooidc:<sub>, portanto prefira-o para administradores humanos.
Como a aplicação funciona
Em cada solicitação/v1/messages, o gateway resolve os limites do desenvolvedor e o gasto até a data do período em uma consulta Postgres. Um desenvolvedor acima de qualquer limite recebe um 429 com error.type: billing_error e o cabeçalho x-should-retry: false.
Para um limite acima de "0", a mensagem informa a data UTC em que esse limite é redefinido. Se você definir admin.blocked_message, o gateway o acrescenta, como neste exemplo:
"0", que uma redefinição não libera, a mensagem não tem data. Quando um desenvolvedor excede vários limites ao mesmo tempo, a mensagem descreve o limite que é redefinido por último. A resposta também carrega um cabeçalho retry-after com os segundos restantes até o fim do período desse limite.
Antes da v2.1.319 no servidor do gateway, a mensagem nomeava o período e a hora de redefinição, como spend limit reached (daily; resets 2026-08-08 00:00 UTC). Antes da v2.1.225, a mensagem era spend limit reached sem período, hora de redefinição ou cabeçalho retry-after.
Na v2.1.227 ou posterior, a referência de protocolo em <public_url>/protocol também lista os cabeçalhos de resposta de limite de uso exato e o corpo 429.
Os limites são redefinidos em limites de calendário UTC: diariamente às 00:00 UTC, semanalmente na segunda-feira e mensalmente no primeiro dia. O gateway nunca bloqueia /v1/messages/count_tokens, porque a contagem de tokens é gratuita.
Como as solicitações são precificadas
Após cada resposta, um medidor de uso lê as contagens de tokens e adiciona o custo aos contadores diário, semanal e mensal. Ele nunca toca nos bytes enviados ao cliente, portanto uma falha de medição não pode quebrar uma resposta. Os valores são estimativas em USD, um disjuntor em vez de uma fatura; para faturamento, reconcilie contra o relatório de uso do seu provedor. O medidor escolhe as taxas de cada solicitação nesta ordem:- Uma linha
pricing.overridescorrespondente para o upstream que serviu a solicitação. Requer v2.1.227 ou posterior. - Preço de lista para o ID do modelo upstream, a string que o gateway envia ao provedor, quando a tabela de custo do Claude Code a reconhece. A tabela aceita formulários Anthropic, Amazon Bedrock, Google Cloud’s Agent Platform e Microsoft Foundry ID.
- Preço de lista para o
models[].idque você mapeou para esse ID upstream, para strings upstream que não carregam nome de modelo, como um ARN de perfil de inferência de aplicação do Amazon Bedrock ou um nome de implantação do Microsoft Foundry. Requer v2.1.218 ou posterior. - O nível de modelo desconhecido de $5/$25 por milhão de tokens de entrada/saída, portanto um ID que o medidor não consegue colocar nunca é gratuito. O gateway avisa na inicialização e uma vez por ID em tempo de execução quando usa este nível.
pricing.multiplier, padrão 1. Requer um servidor do gateway executando Claude Code v2.1.227 ou posterior.
Aborts de cliente também são faturados. Quando um stream termina sem o quadro de uso final do upstream, o medidor fatura uma estimativa de piso de aproximadamente quatro caracteres por token de saída para o texto já enviado ao cliente, portanto abortar solicitações antecipadamente não evita um limite.
Taxas para prompts longos
O preço de lista do Claude Haiku 5.5 tem uma taxa mais alta para prompts acima de um limiar de tokens. Quando o Haiku 5.5 atende uma requisição cujo prompt excede o limiar, um servidor do gateway executando Claude Code v2.1.293 ou posterior precifica a requisição inteira com essa taxa. O medidor conta tokens de entrada, leituras de cache e gravações de cache para esse limiar. Se uma das suas linhaspricing.overrides corresponder à requisição, as taxas dessa linha se aplicam a qualquer comprimento de prompt.
Disponibilidade do Postgres
A pré-verificação consulta o Postgres com um tempo limite de dois segundos. Se o armazenamento estiver inacessível ou expirar o tempo limite, a aplicação falha aberta por padrão: a solicitação prossegue, o gateway registra um aviso e a resposta não carrega cabeçalhosanthropic-ratelimit-unified-*. Defina enforcement.fail_closed_on_error: true para falhar fechado em vez disso, que retorna o mesmo 429 billing_error mas com a mensagem spend limit unavailable e sem período, hora de redefinição ou cabeçalho retry-after. Falha aberta mantém uma interrupção de armazenamento de se tornar uma interrupção de inferência; falha fechada garante nenhum gasto sem medição.
Falha aberta só ajuda enquanto seu balanceador de carga ou orquestrador ainda roteia o tráfego para o gateway. Veja Comportamento de interrupção para store.readiness_grace_seconds, que mantém réplicas passando sua verificação de prontidão através de uma breve interrupção.
Avisos de uso no Claude Code
Claude Code avisa um desenvolvedor conforme ele se aproxima do seu limite: uma vez que a utilização passa 75%, e novamente acima de 95% do seu limite mais consumido. Quando o gateway bloqueia uma requisição, Claude Code mostra a mensagem429 do gateway como está, incluindo seu admin.blocked_message. Ele também mostra o limite em /usage e o repassa ao script de linha de status do desenvolvedor.
Cada exibição requer uma versão mínima do Claude Code na máquina do desenvolvedor e no servidor do gateway:
Os avisos e a porcentagem vêm dos cabeçalhos
anthropic-ratelimit-unified-*, que o gateway adiciona a cada resposta bem-sucedida de /v1/messages para um desenvolvedor que tem um limite. Os cabeçalhos sempre descrevem o limite próprio do desenvolvedor: o gateway remove os cabeçalhos de rate limit do provedor upstream, que descrevem sua cota compartilhada, e nunca os encaminha.
O gasto que um desenvolvedor vê é a própria estimativa do gateway, o mesmo valor com o qual ele aplica o limite. Não é um valor da fatura do seu provedor. Claude Code lê os valores em dólar com uma requisição separada ao gateway, que ele envia mesmo se você definir CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC nas máquinas dos desenvolvedores. Antes da v2.1.295, Claude Code pulava essa requisição quando a variável estava definida, e /usage e a linha de status mostravam a porcentagem e a data de redefinição, sem valores em dólar.
Referência da API de administrador
Os endpoints abaixo são servidos em/v1/organizations/spend_limits.
As convenções espelham a API de Administrador da Anthropic:
- Um
typeem cada objeto - IDs com prefixo
spl_ - Quantidades como strings de número inteiro de centavos USD;
POSTrejeita qualquer outrocurrencycom400 - O envelope de erro
{type: "error", error: {type, message}, request_id} - Um cabeçalho de resposta
request-idem cada resposta de administrador, sucesso ou erro; corpos de erro também o carregam comorequest_id
admin_audit na mesma transação, atribuída a admin-key:<id> ou oidc:<sub>.
O gateway serve os endpoints de limites de gasto apenas. Outras superfícies da API de Administrador, como a fila spend_limit_increase_requests, não fazem parte da API de administrador do gateway.
/effective
GET /v1/organizations/spend_limits/effective retorna o schema SpendSummary da Anthropic: cada linha é um principal para um período, com o limite resolvido, gasto até a data do período e um objeto actor. Diferenças específicas do gateway:
user_idé o OIDCsub.actor.nameeactor.email_addresssãonullaté a primeira solicitação de inferência do principal através do gateway. O gateway não tem diretório de usuários; ele registra valores vistos pela última vez do JWT de sessão de cada usuário.- Cada linha também carrega um array
groups, os últimos grupos IdP vistos do principal. Esta é uma extensão do gateway para que uma UI de administrador possa mostrar cada nível de limite que se aplica; clientes em forma de Anthropic a ignoram. - Sem um filtro
user_ids[], ele lista principais com gasto registrado, porque o gateway não consegue enumerar todos os membros da organização.
group_limit_mode que a aplicação usa, portanto o visualizador mostra o limite que realmente se aplica.
/audit
Retorna a trilha de mutação de limite de gasto: quem mudou qual limite, com snapshots antes/depois, mais recente primeiro. has_more é exato. Este endpoint segue as convenções da API de Administrador local em vez de uma forma de transmissão de primeira parte.
Paginação
A lista bruta pagina porafter_id e before_id, que são IDs spl_… mutuamente exclusivos; os resultados são ordenados por criação e has_more reflete a direção da travessia. /effective pagina pelo token opaco next_page passado de volta como ?page=, com principais ordenados em ordem crescente para que as páginas permaneçam estáveis enquanto o gasto está sendo registrado. limit é 1–1000, padrão 20, em ambos. /audit pagina por after_id, o id numérico do último evento na página anterior, e seu limit padrão é 100.
Ciclo de vida dos dados
O gateway mantém quatro tabelas relacionadas a gastos; uma varredura horária aplica as janelas de retenção:
Quando um desenvolvedor sai, delete qualquer limite por usuário via
DELETE /v1/organizations/spend_limits/{id}; seu gasto e linhas de identidade envelhecem nas janelas de retenção acima. Para apagar uma pessoa imediatamente, para offboarding ou uma solicitação de acesso de assunto de dados (DSAR), execute DELETE FROM principal_emails WHERE principal = '<sub>' diretamente contra o banco de dados do gateway. Isso remove a única tabela contendo seu email, nome e grupos. As linhas spend e admin_audit referenciam apenas o pseudônimo OIDC sub e envelhecem em suas próprias janelas.
Relacionado
- Configuração de
admineenforcement: habilitando a API de administrador e ajustando a retenção - Guia de implantação: schema do Postgres e orientação de backup