SpyBara
Go Premium

claude-apps-gateway-spend-limits.md 2026-06-29 23:02 UTC to 2026-06-30 23:02 UTC

162 added, 0 removed.

2026
Tue 30 23:02 Mon 29 23:02 Sat 27 01:01 Fri 26 23:00 Thu 25 23:58 Wed 24 22:02 Tue 23 22:00 Mon 22 23:59 Fri 19 22:58 Thu 18 22:00 Wed 17 17:02 Tue 16 21:57 Mon 15 23:02 Sat 13 21:59 Fri 12 22:00 Thu 11 23:01 Wed 10 23:57 Tue 9 06:34 Mon 8 06:52 Sat 6 06:24 Fri 5 06:45 Thu 4 06:52 Wed 3 06:53 Tue 2 06:51

Limites de gastos do gateway de aplicativos Claude

Limite o gasto de cada desenvolvedor através do gateway de aplicativos Claude por dia, semana ou mês. Defina limites com uma API de administrador e o gateway os aplica em tempo real em cada solicitação.

Limites de gastos limitam quanto cada desenvolvedor pode gastar através do seu gateway de aplicativos Claude em um determinado dia, semana ou mês. Quando um desenvolvedor ultrapassa seu limite, o gateway retorna 429 na próxima solicitação e os bloqueia até que o período seja redefinido ou um administrador aumente o limite. 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.

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. 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 bloco admin: 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:

curl -sS https://claude-gateway.internal.example.com/v1/organizations/spend_limits \
  -H "x-api-key: $GATEWAY_ADMIN_WRITE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scope": {"type": "organization"}, "amount": "50000", "period": "monthly"}'

Esta solicitação adiciona um limite mais restritivo de $100 por dia para cada membro do grupo contractors:

curl -sS https://claude-gateway.internal.example.com/v1/organizations/spend_limits \
  -H "x-api-key: $GATEWAY_ADMIN_WRITE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"scope": {"type": "rbac_group", "rbac_group_id": "contractors"}, "amount": "10000", "period": "daily"}'
Campo Valores Descrição
scope.type user, rbac_group, organization user direciona um desenvolvedor pelo seu OpenID Connect (OIDC) sub, o ID de usuário estável que seu provedor de identidade atribui; passe-o como scope.user_id. rbac_group direciona um grupo IdP por nome; passe-o como scope.rbac_group_id. organization é o padrão em toda a organização. O gateway aceita todos os três; o POST público da Anthropic é apenas para usuários hoje.
amount String de número inteiro de centavos USD, ou null null é ilimitado. "0" é um limite zero, que bloqueia todas as solicitações.
period daily, weekly, monthly Um escopo pode conter um limite por período, e cada um é aplicado independentemente: um desenvolvedor é bloqueado se ultrapassar qualquer um deles.

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-key correspondendo a uma chave em admin.write_keys para acesso total, ou admin.read_keys para acesso somente GET. Cada chave carrega um id que aparece no log de auditoria como admin-key:<id>, portanto dê ao Terraform, CI e cada automação a sua própria.
  • Um token de portador do gateway cujo groups claim inclui um dos admin.admin_groups. Este é acesso total e é auditado como oidc:<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. Se estiverem acima de qualquer limite, a solicitação retorna 429 com error.type: billing_error e o cabeçalho x-should-retry: false. A mensagem é spend limit reached, seguida pelo seu admin.blocked_message se definido.

/v1/messages/count_tokens é isento. A contagem de tokens é gratuita, portanto é executada independentemente do estado do limite.

Após cada resposta, um medidor de uso lê contagens de tokens da resposta conforme ela é transmitida para o cliente, precifica-os ao preço de lista USD e incrementa contadores Postgres para todos os três buckets de período. O medidor é um único leitor no fluxo, portanto os bytes do cliente não são tocados e uma falha de medição não quebra a resposta.

Limites de gastos estimam gastos a partir de contagens de tokens ao preço de lista USD; eles são um disjuntor, não uma fatura. Para faturamento autoritário, reconcilie contra o relatório de uso do seu próprio provedor, como a API de Administrador de Uso e Custo da Anthropic, logs de invocação no Bedrock ou Cloud Monitoring no Google Cloud.

A precificação usa a mesma tabela que o Claude Code CLI usa para sua própria exibição de custo, com a mesma canonicalização de ID de modelo em formulários Anthropic, Bedrock (us.anthropic.…-v1:0), Agent Platform (claude-…@date) e Foundry ID. Um ID de modelo que a tabela não consegue colocar, como um nome de implantação Foundry ou um ARN de perfil de inferência, é precificado no nível padrão de modelo desconhecido de $5/$25 por milhão de tokens de entrada/saída em vez de zero, portanto um ID não reconhecido não pode contornar um limite indo sem medição. O gateway avisa na inicialização e uma vez por ID em tempo de execução quando um modelo é precificado através do fallback.

Aborts de cliente também são faturados. O upstream relata tokens de saída apenas no quadro terminal do fluxo, portanto um fluxo abortado não os carrega. O medidor mantém uma estimativa de piso conservadora do tamanho do conteúdo transmitido, cerca de quatro caracteres por token, e a fatura quando e apenas quando o quadro de uso terminal está faltando. Um fluxo completo sempre fatura a contagem relatada pelo upstream. Sem isso, um desenvolvedor limitado poderia transmitir saída e abortar cada solicitação imediatamente antes do final, gastando sem nunca ser contado.

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 e o gateway registra um aviso. Defina enforcement.fail_closed_on_error: true para falhar fechado em vez disso, que retorna o mesmo 429 billing_error com a mensagem spend limit unavailable. 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.

Referência da API de administrador

Os endpoints abaixo são servidos em /v1/organizations/spend_limits.

Método e caminho Descrição
GET /v1/organizations/spend_limits Listar limites configurados. Consulta: ?limit=&after_id=&before_id=.
POST /v1/organizations/spend_limits Criar ou substituir um limite para {scope, period}.
GET /v1/organizations/spend_limits/{id} Buscar um limite por seu ID com prefixo spl_.
DELETE /v1/organizations/spend_limits/{id} Deletar um limite. Retorna {type: "spend_limit_deleted", id}.
GET /v1/organizations/spend_limits/effective Limite resolvido e gasto até a data por principal por período.
GET /v1/organizations/spend_limits/audit Trilha de mutação de administrador, mais recente primeiro. Consultas: ?limit=.

As convenções espelham a API de Administrador da Anthropic:

  • Um type em cada objeto
  • IDs com prefixo spl_
  • Quantidades como strings de número inteiro de centavos USD; POST rejeita qualquer outro currency com 400
  • O envelope de erro {type: "error", error: {type, message}, request_id}
  • Um cabeçalho de resposta request-id em cada resposta de administrador, sucesso ou erro, correspondendo ao request_id do corpo

Cada mutação escreve uma linha antes/depois para 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 OIDC sub.
  • actor.name e actor.email_address são null até 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.

Limites originários de grupo são resolvidos contra esses últimos grupos vistos com o mesmo desempate group_limit_mode que a aplicação usa, portanto o visualizador mostra o limite que realmente se aplica.

Parâmetro de consulta Descrição
user_ids[] Repetível. Filtrar para principais específicos por OIDC sub.
period[] Repetível. Filtrar para linhas daily, weekly ou monthly.
sort spend_desc lista os maiores gastadores primeiro. Requer exatamente um period[].
q Filtro de substring insensível a maiúsculas/minúsculas sobre o OIDC sub, último email visto e último nome de exibição visto.
limit / page Tamanho da página, 1–1000 com padrão de 20, e o cursor opaco da resposta anterior next_page.

`/audit`

Retorna a trilha de mutação de limite de gasto: quem mudou qual limite, snapshots antes/depois e a razão opcional, 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 por after_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.

Ciclo de vida dos dados

O gateway mantém quatro tabelas relacionadas a gastos; uma varredura horária aplica as janelas de retenção:

Tabela Conteúdo Retenção
spend Contadores até a data do período por principal em centavos admin.spend_retention_months, padrão 13
spend_limits Os limites configurados Até deletado via API
admin_audit A trilha de mutação admin.audit_retention_days, padrão 365
principal_emails Último email visto de cada principal, nome de exibição e grupos IdP. Contém PII. admin.identity_retention_days desde última atividade, padrão 90

identity_retention_days é deliberadamente mais curto que spend_retention_months: uma identidade desprovisionada para de se atualizar e envelhece, enquanto seus contadores de gasto anônimos permanecem para relatórios ano a ano.

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.