Vercel AI Gateway: como limitar gastos por usuário

Um agente de programação fora de controle não precisa mais dividir o mesmo freio financeiro com o app em produção. Em 31 de agosto de 2026, o Vercel AI Gateway passou a oferecer orçamentos por usuário. Com isso, os gastos das chaves de API atribuídas a uma pessoa podem ser interrompidos, enquanto uma chave de produção atribuída à equipe continua funcionando — desde que essa chave e a equipe ainda tenham orçamento disponível. A novidade muda a forma de controlar a conta, não o preço dos modelos.

Vercel AI Gateway em uma frase

Defina uma cota individual para as chaves dos agentes de cada pessoa e mantenha as chaves compartilhadas de produção sob responsabilidade da equipe.

Esse é o mecanismo inteiro. O orçamento de um usuário soma os gastos de todas as chaves de API do AI Gateway atribuídas ao mesmo membro. Quando a cota acaba, novas requisições feitas com essas chaves retornam HTTP 402, enquanto o tráfego que não depende do orçamento dessa pessoa pode continuar.

Antes desse lançamento, a Vercel já permitia limitar os gastos da equipe, de um projeto ou de uma única chave de API. O novo escopo por usuário funciona ao lado desses controles e resolve outro problema: um desenvolvedor pode usar várias chaves no Codex, Claude Code, Cursor ou em outra carga autônoma, mas o financeiro ainda precisa de um teto único para todo o gasto dessa pessoa no gateway.

O que realmente entra na conta de cada usuário

A configuração decisiva é a atribuição de gastos: o rótulo de propriedade que a Vercel associa a uma chave de API para contabilizar o orçamento.

Por padrão, as novas chaves recebem atribuição User. Chaves antigas sem atribuição continuam vinculadas à Team por compatibilidade com versões anteriores. Uma chave criada pela API sem metadata.spendAttribution também entra na conta da Team.

Isso cria quatro caminhos distintos para as requisições:

O gasto não é repartido entre esses orçamentos. Ele é registrado, ao mesmo tempo, em todos os medidores aplicáveis. Uma requisição feita com a chave de um membro precisa caber no orçamento da chave, no orçamento do usuário e no orçamento da equipe. Se qualquer um deles se esgotar, a requisição é interrompida.

É por isso que o tráfego compartilhado de produção exige uma decisão explícita. Se um desenvolvedor criar uma nova chave para um app voltado a clientes, ela ficará atribuída a essa pessoa por padrão. Nesse caso, a cota individual pode derrubar o app. Na página de chaves de API do AI Gateway, altere Spend attribution para Team; assim, somente os orçamentos da própria chave e da equipe serão aplicados.

A conta de risco mudou

Limites por usuário transformam um risco compartilhado em cotas que podem ser distribuídas antes de a fatura chegar.

Considere um exemplo hipotético, não um preço da Vercel. Uma equipe de 8 pessoas tem orçamento mensal de $1,000. Sete membros recebem o padrão mensal de $50. Uma liderança recebe um orçamento personalizado de $150 porque a função exige cargas mais pesadas de agentes.

O teto das chaves pessoais é:

7 × $50 + 1 × $150 = $500 per month

Esses $500 não ficam ao lado do orçamento da equipe, mas dentro dele. Se as chaves atribuídas aos membros consumirem primeiro os $500 completos, os mesmos $500 também contarão contra o limite de $1,000 da equipe. Nesse cenário simplificado, restam $500 antes do teto da equipe para o tráfego de produção atribuído à Team.

Nada, porém, fica reservado. A produção pode gastar primeiro, e toda requisição ainda precisa encontrar espaço no orçamento da equipe. O benefício é mais específico: nenhum integrante consegue consumir, por meio de suas chaves atribuídas, mais do que a própria cota antes que todos os demais percam o acesso.

Esse modelo difere do controle nativo da OpenAI, no qual um agente precisa ter seu próprio projeto para receber um teto de projeto obrigatório. O guia sobre controle de orçamento da API da OpenAI explica esse modelo de isolamento. Na Vercel, o escopo por usuário pode reunir várias chaves atribuídas ao mesmo membro sem exigir um projeto por pessoa.

O recurso não reduz o preço dos tokens. O AI Gateway continua cobrando os preços de tabela dos provedores, sem acréscimo sobre tokens nem taxa de plataforma. O ganho está na contenção de perdas e na clareza sobre quem gerou o gasto, não em inferência mais barata.

Quatro equipes que ganham um fluxo de trabalho melhor

Liderança de engenharia com vários agentes de programação

Defina um orçamento padrão por usuário para a equipe e atribua valores personalizados a quem usa mais. Um desenvolvedor pode executar agentes diferentes com chaves separadas, mas todas essas chaves continuam reunidas sob um único teto pessoal.

O resultado é um loop noturno com limite. Se um agente insistir em repetir uma tarefa com falha, as requisições daquele desenvolvedor param sem derrubar automaticamente um serviço de produção atribuído à Team.

Operação de agência protegendo a margem dos clientes

Dê a cada profissional uma chave atribuída ao próprio membro e uma cota padrão. Crie um orçamento personalizado para quem estiver conduzindo uma migração intensiva em modelos ou um projeto curto para um cliente.

O resultado é uma exceção com nome e responsável. É possível liberar mais gastos para uma pessoa sem aumentar a cota de toda a equipe nem transformar o orçamento geral da agência no único disjuntor financeiro.

Liderança de plataforma separando pessoas da produção

Faça uma auditoria de todas as chaves do AI Gateway e marque os serviços compartilhados como Team. Mantenha as chaves pessoais dos agentes de programação atribuídas a quem as criou.

O resultado é o isolamento de falhas. Quando a cota de uma pessoa se esgota, o tráfego dos agentes dela para; a carga voltada aos clientes continua até acabar o orçamento da própria chave ou da equipe.

Liderança financeira ou operacional responsável pela política

Uma pessoa com função Owner pode conceder a permissão AI Gateway Budget Manager sem entregar toda a função de Owner. Quem recebe essa permissão consegue gerenciar orçamentos de usuários, valores padrão e atribuições de chaves. Ao mesmo tempo, todas as funções da equipe, exceto Contributor, podem consultar as páginas de orçamento.

O resultado é uma responsabilidade operacional de verdade. O financeiro define o teto, a engenharia consegue acompanhá-lo e uma mudança de orçamento não precisa esperar pela única pessoa que administra toda a equipe na Vercel.

Como configurar sem vincular a produção a uma pessoa

Os orçamentos por usuário exigem a CLI da Vercel na versão 59.6.2 ou mais recente. Os comandos abaixo foram verificados com a versão 59.6.2 nesta execução.

1. 1

   Atualize e confira a CLI

   Execute a atualização documentada e confirme que a versão instalada é, no mínimo, a 59.6.2.

   vercel upgrade
   vercel --version

2. 2

   Defina a cota padrão

   Neste exemplo, cada membro sem orçamento personalizado recebe sua própria cota mensal de $50. Não são $50 compartilhados pelo grupo.

   vercel ai-gateway budgets defaults set user --limit 50 --refresh-period monthly

3. 3

   Crie um limite personalizado para quem usa mais

   O orçamento personalizado substitui o padrão para aquela pessoa. A Vercel aceita endereço de email, nome de usuário ou ID de usuário.

   vercel ai-gateway budgets set user lead@example.com --limit 150 --refresh-period monthly
   vercel ai-gateway budgets list

4. 4

   Transfira as chaves compartilhadas para a equipe

   Abra o AI Gateway, acesse API Keys, edite cada chave usada por uma carga compartilhada ou voltada aos clientes e defina Spend attribution como Team. Novas chaves recebem User por padrão, então inclua essa revisão no processo de criação de chaves de produção.

5. 5

   Ative alertas quando alguém precisar acompanhá-los

   Orçamentos personalizados podem enviar emails ao atingir 50%, 75% e 100% do limite. Os alertas vêm desativados, e um orçamento padrão não envia notificações. Portanto, crie um orçamento personalizado quando uma pessoa específica precisar ser avisada antes da interrupção.

Orçamentos mensais são redefinidos no primeiro dia do mês, à meia-noite UTC. Os diários são redefinidos à meia-noite UTC; os semanais, na segunda-feira à meia-noite UTC; e none cria um limite cumulativo que nunca é redefinido.

Como testar a interrupção e a retomada em staging

Nenhum orçamento de uma equipe Vercel real foi alterado para este artigo, pois esta execução não contou com uma equipe nem uma chave descartáveis. Por isso, o teste seguro deve ser feito por você em staging. O comportamento do 402 e os tempos de propagação abaixo fazem parte do contrato documentado pela Vercel; não são um benchmark de conta apresentado como resultado desta execução.

Use um membro dedicado a staging e uma chave atribuída a ele. Não execute esse teste com uma chave de produção.

1. 1

   Comece por um gasto visível

   Use vercel ai-gateway budgets list para conferir o gasto do membro de staging no período atual. Se o valor já estiver acima do mínimo documentado de $1, você pode acionar o limite sem gerar nem um dólar de novo tráfego de teste.

2. 2

   Reduza o teto do usuário de staging

   Ao editar um orçamento, o gasto já acumulado no período atual é preservado. Defina $1 para o usuário de staging e aguarde a propagação.

   vercel ai-gateway budgets set user staging@example.com --limit 1 --refresh-period monthly

3. 3

   Envie uma requisição pela chave desse membro

   Exporte a chave de staging atribuída ao membro como AI_GATEWAY_API_KEY e use o formato de requisição HTTP bruta documentado pela Vercel.

   curl https://ai-gateway.vercel.sh/v1/chat/completions \
     -H "Authorization: Bearer $AI_GATEWAY_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "model": "openai/gpt-5.6-sol",
       "messages": [
         {
           "role": "user",
           "content": "Invent a new holiday and describe its traditions."
         }
       ]
     }'

   Quando o orçamento do usuário estiver ativo e esgotado, a requisição deverá retornar HTTP 402 com o tipo de erro quota_for_entity_exceeded. Se o 402 trouxer outro tipo, o problema pode ser o saldo de créditos da equipe, e não um orçamento.

4. 4

   Aumente o limite e tente de novo

   Eleve o limite personalizado para um valor acima do gasto exibido por budgets list. Este comando documentado usa $100.

   vercel ai-gateway budgets set user staging@example.com --limit 100 --refresh-period monthly

   Mudanças de orçamento costumam se propagar em dezenas de segundos, mas podem levar até cerca de cinco minutos para uma chave ativa. Aguarde e repita a mesma requisição. Ela deverá voltar a funcionar, a menos que outro orçamento aplicável — o da chave ou o da equipe — também tenha se esgotado.

5. 5

   Restaure a política planejada

   Reaplique ao usuário de staging o limite personalizado previsto. Remover o orçamento personalizado nem sempre libera o tráfego, pois o usuário volta ao padrão quando ele existe. Se esse orçamento padrão já estiver esgotado, o bloqueio continua.

Dois limites que passam despercebidos com facilidade

Primeiro, os gastos via BYOK ficam fora de todos os orçamentos do AI Gateway. Quando o gateway usa suas próprias credenciais de provedor, esse consumo é contabilizado separadamente e não pode ser contido pelo limite de um usuário. Uma requisição BYOK que falha também pode recorrer às credenciais de sistema da Vercel e consumir o saldo de créditos do AI Gateway da equipe.

Segundo, as páginas da própria Vercel divergem hoje sobre os tokens de app. O anúncio de 31 de agosto afirma que os limites por usuário abrangem chaves de API atribuídas e tokens de app. Já a documentação atual sobre orçamentos diz que tokens de app não têm atribuição a membros e nunca entram no orçamento de um usuário.

O que fazer na segunda-feira

Coloque isso em prática nesta semana se vários integrantes usam agentes de programação ou outras cargas não supervisionadas com suas próprias chaves do AI Gateway. Espere se todo o tráfego usa apenas tokens OIDC de projeto ou credenciais de provedor via BYOK, pois os orçamentos por usuário não controlam esses caminhos. Para quem trabalha sozinho, com uma chave e um orçamento de equipe, quase nada muda.

Na segunda-feira, classifique cada chave do gateway como PESSOA ou COMPARTILHADA. Primeiro, transfira as chaves compartilhadas de produção para a atribuição Team. Depois, defina um único orçamento mensal padrão por usuário, crie somente as exceções personalizadas que a empresa consegue justificar e execute o teste de staging com 402 do bloqueio à retomada, passando pelo aumento do limite. O orçamento só estará pronto quando a produção ficar fora da cota de uma pessoa e quem opera o sistema souber qual limite interrompeu a requisição.

Para receber mais orientações práticas sobre controle de gastos com IA e fluxos de produção, assine a newsletter.