Para limitar tokens por usuário, a aplicação precisa reservar orçamento antes de chamar o modelo e acertar o saldo quando conhecer o consumo real. Consultar o saldo e descontar apenas no fim permite que chamadas simultâneas gastem a mesma cota. A admissão deve acontecer no servidor, de forma atômica, usando uma identidade autenticada e uma chave única por operação.
Esse controle resolve uma pergunta específica: esta pessoa pode iniciar esta chamada agora? Ele complementa a estimativa de custos e os limites do fornecedor. O desenho abaixo apresenta reservas, concorrência, devoluções e tratamento de falhas. As quantidades dos exemplos são hipotéticas e servem para explicar a política, sem representar limites comerciais de qualquer API.
Resumo rápido
- Separe cota por período, limite de chamadas simultâneas e orçamento por tarefa.
- Reserve entrada estimada e saída máxima antes de liberar uma chamada.
- Use uma operação atômica para verificar o saldo e criar a reserva.
- Ao concluir, substitua a estimativa pelo consumo informado pela API.
- Falhas de rede exigem reconciliação; timeout não comprova consumo zero.
Defina o que a cota mede e quem pode usá-la
Token é uma unidade de processamento de texto; a política precisa dizer quais tokens entram na conta. Você pode controlar entrada e saída separadamente ou somá-las em uma cota operacional. Se modelos têm custos diferentes, uma quantidade igual de tokens não representa gasto igual. Nesse caso, mantenha também um orçamento monetário interno, com tabela de preços versionada e regras claras.
O guia de tokens e custo de API ajuda a estimar despesas. Aqui, a preocupação é impedir que duas requisições usem um saldo que só comporta uma. O cálculo financeiro e o mecanismo de admissão devem compartilhar dados, mas precisam de critérios próprios. Uma reserva de tokens não é uma fatura emitida ao usuário.
Obtenha a identidade da sessão autenticada, nunca de um campo livre enviado pelo navegador. Inclua a organização ou empresa contratante quando houver várias equipes. Defina o período da cota, o fuso usado no fechamento e o tratamento de chamadas iniciadas antes da virada. Uma opção é manter a reserva vinculada ao período de admissão até o acerto final.
Os limites da API da OpenAI operam no contexto de organizações e projetos, e não substituem as cotas dos usuários do seu produto. Confira a documentação e o painel para o contrato efetivo da conta. A página de integração com OpenAI e ChatGPT contextualiza esse ecossistema.
Separe os limites que protegem a operação
Uma cota mensal evita consumo acumulado excessivo, mas não impede que alguém abra muitas chamadas ao mesmo tempo. O limite de concorrência controla quantas operações ficam ativas; o limite de frequência controla a velocidade de chegada. Agentes com vários passos precisam ainda de orçamento por tarefa, para que uma única solicitação não use o saldo inteiro.
| Controle | Pergunta respondida | Ação ao atingir |
|---|---|---|
| Cota por usuário e período | Quanto ainda pode consumir? | Recusar ou solicitar ampliação conforme o plano |
| Concorrência por usuário | Quantas chamadas podem ficar ativas? | Enfileirar ou pedir que aguarde |
| Limite por tarefa | Até onde esta execução pode continuar? | Parar em um ponto explicável |
| Capacidade do fornecedor | O projeto pode enviar agora? | Aguardar capacidade ou reagendar |
| Orçamento global | A operação pode assumir mais gasto? | Bloquear novas admissões de forma controlada |
Decida a precedência desses controles e devolva um motivo específico ao cliente. Falta de cota mensal não se resolve com tentativas a cada segundo. Capacidade momentânea pode admitir uma fila curta. Evite uma fila ilimitada que acumula promessas de atendimento sem prazo. Antes de despachar uma chamada enfileirada, confira novamente sua autorização e sua reserva.
Reserve o orçamento em uma transação curta
Estime a entrada completa: instruções, conversa, resultados de ferramentas e documentos anexados na forma processada pela API. Conte com o mecanismo adequado ao modelo e ao tipo de entrada. Uma estimativa baseada apenas na última frase do usuário deixa parte do trabalho fora da reserva. Defina um teto de saída permitido pela operação e use o parâmetro documentado pelo endpoint escolhido.
Modelos com raciocínio podem consumir tokens além do texto visível. A documentação de raciocínio da OpenAI descreve essa distinção. Não estime consumo final contando caracteres que apareceram na tela. A reserva deve considerar as categorias relevantes e o teto aplicável ao modelo, sem somar duas vezes campos que já estejam incluídos no total.
Imagine uma cota com 10.000 tokens disponíveis. Uma chamada pede reserva de 6.000. Se duas chamadas leem o saldo antes da atualização, ambas podem ser aceitas. A solução é executar verificação, alteração do saldo reservado e criação da operação no mesmo mecanismo de exclusão mútua. No PostgreSQL, isso pode usar uma transação com bloqueio da linha da cota.
BEGIN;
-- Bloquear a cota do usuário e do período com FOR UPDATE.
-- Localizar a operação pela chave única de idempotência.
-- Se já existir, devolver seu estado sem reservar novamente.
-- Conferir: limite - consumido - reservado >= nova_reserva.
-- Conferir também o limite de operações ativas.
-- Criar a reserva e atualizar os contadores.
COMMIT;
-- Só depois: despachar a chamada externa.O exemplo é pseudocódigo de transação, não uma função pronta. Os bloqueios de linha do PostgreSQL fundamentam essa opção. Todas as instâncias da aplicação devem passar pelo mesmo controle. Não mantenha o bloqueio aberto enquanto espera o modelo responder, pois isso transforma latência externa em contenção no banco.
No Redis, uma alternativa envolve transações condicionais ou scripts com as garantias apropriadas. A documentação de transações do Redis explica como WATCH detecta alterações concorrentes. Um GET seguido de SET, sem proteção, não resolve a disputa. Para reservas financeiras, avalie persistência, recuperação e consistência entre o cache e o registro durável.
Acerte o consumo e reconcilie estados incertos
Mantenha estados explícitos: reservada, enviada, concluída, liberada e pendente de reconciliação. Ao receber o consumo final, uma transação libera a reserva e acrescenta o consumo efetivo ao acumulado. Se a reserva foi de 6.000 e o consumo de 4.200, a diferença de 1.800 volta a ficar disponível. Esses números explicam apenas a mecânica.
O acerto precisa ser idempotente. Um evento final repetido não pode descontar duas vezes. Proteja a transição de estado e registre um lançamento único por operação. Use o identificador da chamada do fornecedor quando disponível, junto da chave interna. Reutilizar uma chave com parâmetros diferentes deve produzir conflito, não uma chamada silenciosamente alterada.
Se a aplicação cair depois de reservar e antes de enviar, um trabalhador pode retomar o despacho. O intervalo entre envio externo e registro local do resultado é mais delicado: a aplicação pode não saber se o fornecedor recebeu o pedido. Uma outbox ajuda a não perder o trabalho, mas sozinha não garante execução única no serviço externo. Verifique as garantias de idempotência do endpoint antes de reenviar.
Timeout, fechamento da aba e cancelamento local não comprovam consumo zero. Não devolva automaticamente todo o saldo nessas situações. Preserve um estado pendente e busque evidência no registro da operação ou no mecanismo de consulta oferecido pelo fornecedor. Se não houver recuperação possível, aplique uma política conservadora, documentada, com prazo e tratamento humano para divergências.
Na transmissão progressiva, chamada de streaming, o texto chega antes do encerramento. A documentação de streaming da OpenAI apresenta eventos de ciclo de vida. Trate conclusão, falha e resposta incompleta separadamente. A desconexão do cliente deve disparar uma rotina no servidor, sem depender de o navegador enviar a última mensagem.
Defina ainda o que fazer quando o consumo superar a reserva. Uma estimativa não é uma garantia absoluta. Registre o consumo verdadeiro, sinalize a divergência e impeça novas admissões quando necessário. Nunca apague a diferença para manter o saldo bonito. Investigue entradas subestimadas, categorias esquecidas e configurações de saída inconsistentes.
Controle agentes, retentativas e observabilidade
Para um agente, a tarefa pode reservar um envelope de orçamento e distribuir parte dele a cada chamada. Outra opção é reservar por chamada e verificar um teto acumulado da tarefa antes de cada passo. Evite somar o envelope inteiro e cada sub-reserva como se fossem despesas independentes: esse erro bloqueia saldo duas vezes.
Uma retentativa também precisa passar pelo controle. Se não houver confirmação de que a tentativa anterior deixou de consumir, mantenha as duas exposições cobertas. Use limites de tentativas e espera progressiva para falhas transitórias. Não repita indefinidamente uma rejeição de autorização ou de cota. Ao trocar de modelo, refaça a estimativa conforme o novo contrato.
Registre usuário interno, organização, período, tarefa, modelo, estimativa, reserva, consumo final e motivo das transições. Não é necessário guardar o prompt completo para medir orçamento. Acompanhe reservas antigas, diferença entre estimativa e consumo, negações por motivo e quantidade de acertos repetidos rejeitados. Essas métricas ajudam a perceber falhas antes de uma reclamação.
O texto sobre observabilidade de agentes de IA aprofunda os registros de execução. No mecanismo de admissão, teste situações concorrentes de verdade: duas chamadas disputando o último saldo, evento final duplicado e queda entre reserva e envio. Verifique o saldo final e os estados, não apenas a resposta HTTP.
Exemplo: plataforma de atendimento em Recife
Considere uma plataforma de atendimento usada por pequenas lojas em Recife. O cenário é ilustrativo. Cada atendente recebe uma cota operacional por período e pode pedir resumos de conversas. Um agente separado auxilia em casos complexos, com várias consultas ao modelo. O gestor precisa impedir que poucos usuários consumam toda a capacidade compartilhada.
Ao solicitar um resumo, o servidor autentica o atendente, monta a entrada e reserva o teto da operação. Se outra chamada já ocupou o limite de concorrência, o pedido aguarda em uma fila curta ou recebe uma orientação clara. A interface mostra que há uma operação em andamento e não incentiva cliques repetidos.
Quando o resumo termina, o servidor acerta o uso e libera a diferença. Se a rede cair, o pedido fica pendente até a reconciliação. O gestor consegue distinguir saldo consumido de saldo reservado. Para o agente, cada novo passo verifica o orçamento restante da tarefa. Esse desenho permite explicar uma interrupção sem atribuí-la genericamente a uma falha da IA.
Erros comuns
- Descontar só depois da resposta. Chamadas simultâneas conseguem usar o mesmo saldo.
- Aceitar a identidade enviada pelo cliente. O usuário poderia apontar a cobrança para outra pessoa.
- Devolver tudo em qualquer erro. A chamada pode ter sido processada antes da falha de rede.
- Usar expiração como prova de cancelamento. Uma reserva vencida exige investigação do estado externo.
- Confundir tokens visíveis com consumo total. Use os campos de uso definidos pelo fornecedor.
- Repetir o acerto sem trava. Eventos duplicados precisam encontrar uma operação já finalizada.
Perguntas frequentes
Posso controlar tudo no navegador?
Não. A interface pode mostrar saldo e desabilitar um botão, mas a autorização efetiva precisa acontecer no servidor. Outros clientes e chamadas simultâneas devem seguir a mesma regra.
O limite de tokens substitui um limite financeiro?
Não necessariamente. Modelos e categorias de uso podem ter preços distintos. Se a meta é proteger gasto, acompanhe também a exposição monetária com preços verificados e versionados.
Preciso reservar a cota inteira de uma conversa?
Não. Você pode reservar por chamada e manter um teto por tarefa. Recalcule a entrada a cada passo, porque histórico e resultados de ferramentas aumentam o contexto.
Uma reserva pode expirar automaticamente?
Pode ter prazo operacional, mas a expiração não deve liberar saldo cegamente. Primeiro diferencie uma chamada nunca enviada de outra cujo consumo ainda é desconhecido.
