Resumo: você definiu uma cota para a chave API e, ainda assim, o custo pode sair acima do esperado. Este artigo explica o motivo e decompõe o controle de orçamento dos testes com IA em três linhas de orçamento que têm uma ordem de precedência entre si.
Já adiantando a conclusão: a cota da Key no gateway é um teto flexível (soft limit) e, com requisições concorrentes, não pode ser tratada como limite rígido de fatura. Usando como exemplo a documentação de tokens da APIYI, a cota é verificada no início da requisição. Várias requisições podem passar pela verificação ao mesmo tempo, ou uma única requisição já ser caríssima por si só — nos dois casos, o consumo final pode ultrapassar a cota definida.
O caminho confiável é trabalhar com três camadas:
- O backend da aplicação faz a verificação antes de enviar a requisição e reserva o orçamento de forma atômica.
- No gateway, emita uma Key separada para o tráfego de teste, com cota e lista de modelos permitidos (whitelist), reduzindo o alcance do impacto caso essa Key seja usada indevidamente.
- O alerta de saldo da conta serve apenas para notificar, e existe para disparar uma resposta humana.
As responsabilidades dessas três camadas não se substituem entre si. A verdadeira admissão de orçamento acontece no livro-caixa da própria aplicação.

Mapa de conhecimento e índice: ordem e divisão de responsabilidades das três linhas de orçamento
A tabela abaixo acumula duas funções: mapa de conhecimento e índice. Ela mostra em que ordem as três linhas de orçamento entram em ação, o que cada uma cobre, por que foram organizadas desse jeito e qual seção do texto corresponde a cada item.
| Ordem | Linha de orçamento | Do que se encarrega | Por que fica nesta posição | Objetivo | Texto |
|---|---|---|---|---|---|
| Premissa | Entender a cota flexível | Distinguir a verificação antes da requisição, a reserva e o débito efetivo | Sem clareza sobre a sequência de cobrança, as três camadas seguintes não têm como ser projetadas | Entender como o estouro acontece | 1, 1.1 |
| Primeira | Orçamento no backend da aplicação | Fazer reserva atômica e liquidação por usuário e por pool de teste | Só a aplicação sabe “quem está usando e quanto pode usar” | Barrar o estouro antes de enviar a requisição | 2.1, 3 |
| Segunda | Key de teste independente | Cota, whitelist de modelos e isolamento em relação ao tráfego de produção | Se a aplicação tiver bug, o gateway é a segunda camada de fronteira | Reduzir a superfície de exposição de uma única Key | 2.2 |
| Terceira | Alerta de saldo da conta | Notificar quando o saldo cai abaixo do limite | O alerta é um sinal posterior, sem capacidade de bloqueio | Fazer alguém intervir a tempo | 2.3 |
| Implementação | Livro-razão de concorrência e checklist de lançamento | Reserva, liquidação, tratamento de falhas, reconciliação e mensagens amigáveis | Transformar os princípios anteriores em um processo verificável | Conseguir validar item por item antes de ir para produção | 3, 4 |
Sugestão de ordem de leitura: comece pela seção 1 para entender a sequência temporal, depois leia a seção 2 para esclarecer a divisão de responsabilidades, e a seção 3 para a parte de implementação. A seção 4 funciona bem como lista de verificação separada, na hora de subir para produção.
Para saber: termos necessários antes de entender a linha de cota
| Termo | Explicação breve |
|---|---|
| Limite flexível | A cota é verificada no início da solicitação; passar na verificação não garante que o consumo total não ultrapasse a linha |
| Pré-dedução | O gateway deduz antecipadamente uma parte da cota com base na estimativa e liquida pelo uso real após o término da solicitação |
| Reserva atômica | Completa “verificar o saldo e ocupar” em uma única operação indivisível, evitando que solicitações concorrentes passem ao mesmo tempo |
| Reserva em trânsito | A parcela da cota que ainda aparece como ocupada no livro-razão quando a solicitação já foi enviada, mas o custo real ainda não foi confirmado |
| remain_quota | Campo de cota total de uso único do token da APIYI; conforme a documentação, 500000 corresponde a $1 |
| Conciliação | Conferir item a item os logs do gateway com o livro-razão próprio, corrigindo desvios entre estimativa e real |
1 Por que a cota de uma chave API pode ser excedida por concorrência
A documentação de tokens da APIYI é bem explícita: a cota da chave é um limite flexível, verificado no início da solicitação. Por isso, solicitações concorrentes ou uma única solicitação de alto custo podem fazer o consumo real ultrapassar a cota definida. Isso é uma característica da própria estrutura de cobrança “verifica no início, liquida no final”, e não tem relação com a existência ou não de bug em alguma plataforma.
Dá para entender com um cenário hipotético (os números são apenas ilustrativos, não medições reais). Uma chave de teste tem cota restante equivalente a $1 e, no mesmo instante, chegam 20 solicitações. No início, cada solicitação vê “saldo positivo”, então todas são liberadas. Quando elas vão terminando e são liquidadas pelo uso real, o consumo total já ultrapassou em muito $1. Mesmo sem concorrência, uma solicitação com contexto longo e saída maior pode ter custo único superior à cota restante.
Há ainda dois mal-entendidos comuns que vale esclarecer:
- A cota não se recupera automaticamente todos os dias. A documentação diz que remain_quota é uma cota total de uso único; para “redefinir diariamente”, a aplicação precisa escrever seu próprio script agendado.
- A lista de modelos permitidos não equivale a um teto de custo. Ela só restringe quais modelos podem ser chamados; não limita o número de chamadas nem o tamanho de cada chamada no mesmo modelo.

1.1 Os três momentos da cota de uma chave API: verificação antes da solicitação, estimativa e débito real
Uma chamada tem três momentos do ponto de vista da cobrança, e cada um responde a uma pergunta diferente:
| Momento | Onde ocorre | Pergunta que responde | Pode servir como limite rígido |
|---|---|---|---|
| Verificação antes da solicitação | Gateway, no início da solicitação | Esta chave ainda tem cota neste momento? | Não; sob concorrência, várias solicitações podem passar ao mesmo tempo |
| Estimativa e pré-dedução | Gateway, com base na estimativa | Quanto esta solicitação provavelmente vai ocupar? | Não; há diferença entre estimativa e real |
| Débito real | Gateway, após o término da solicitação | Quanto esta solicitação realmente usou? | Dado posterior; não serve para controle de admissão |
A explicação da APIYI sobre a cota de pré-dedução é: o gateway faz uma pré-dedução com base na estimativa e liquida depois pelo uso real; esse mecanismo não substitui a reserva atômica do lado da aplicação. A pré-dedução do gateway existe para a cobrança dele próprio e não sabe quanta cota de teste ainda resta para um usuário seu hoje. Por isso, a pergunta “esse usuário pode enviar mais uma solicitação?” só pode ser respondida pelo backend da aplicação.
2 As três linhas de orçamento para testes de IA
As três linhas correspondem a três tipos de risco: uso excessivo no nível da lógica de negócio, abuso ou vazamento no nível da Key, e esgotamento do saldo no nível da conta. O API4 “Unrestricted Resource Consumption” do OWASP API Security Top 10 (2023) trata exatamente da mesma categoria de problema: interfaces que não impõem limites ao consumo de recursos geram riscos tanto para o serviço quanto para o custo. No caso das interfaces de IA, o risco de custo costuma ser mais direto.
2.1 Primeira linha de orçamento: o orçamento de usuário e do pool de testes no backend da aplicação
Esta é a única camada capaz de fazer o “controle de entrada”, e ela precisa gerenciar dois níveis:
- Orçamento por usuário: a cota total ou a cota diária de cada usuário de teste. A cota diária é redefinida por uma tarefa agendada da própria aplicação, sem depender do gateway.
- Orçamento do pool de testes: o teto total compartilhado por todos os usuários de teste. Mesmo que nenhum usuário individual ultrapasse o limite, o custo total precisa ter um teto quando o número de usuários dispara.
Uma requisição só é liberada se passar, ao mesmo tempo, pela reserva no nível do usuário e pela reserva no nível do pool, e as duas precisam ser concluídas na mesma operação atômica ou na mesma transação. Caso contrário, ainda surge a condição de corrida em que “a reserva do usuário foi bem-sucedida, mas o pool já está cheio”.
Essa camada também precisa decidir, no servidor, a escala da requisição: qual modelo é permitido, qual é o limite de max_tokens e qual é o comprimento máximo de entrada. Esses parâmetros não podem ser repassados diretamente a partir do que o frontend envia; caso contrário, basta o usuário alterar um parâmetro para que o valor estimado fique distorcido.
2.2 Segunda linha de orçamento: uma Key de teste dedicada, cota e lista de modelos permitidos
No lado do gateway, emita uma Key separada para o tráfego de teste, totalmente isolada do tráfego de produção. A responsabilidade dessa Key é limitar a superfície de exposição: se o registro contábil da aplicação tiver um bug, ou se a Key vazar, a perda fica restrita à cota dessa Key e não afeta as operações de produção.
Pontos de atenção na configuração:
- Defina a cota como “orçamento do pool de testes + uma margem de segurança”. Ela deve ser um pouco maior que o orçamento do pool no lado da aplicação, para servir como rede de segurança; não a configure igual ao orçamento do pool, caso contrário a reserva na camada da aplicação se torna inútil.
- A lista de modelos permitidos deve conter apenas os modelos liberados para teste. Ela impede que a Key de teste seja usada para chamar modelos mais caros, mas não limita quantidade nem escala; por isso, o limite de escala no servidor descrito na seção 2.1 continua sendo obrigatório.
- Como a cota é um limite flexível (soft limit), essa linha permite “ultrapassagens leves”. O objetivo dela é manter o excesso dentro de uma faixa aceitável; não espere que ela garanta zero estouro de orçamento.
A prática comum de separar Key, cota e logs por projeto é outro assunto; aqui destaco apenas um ponto: uma Key separada para o tráfego de teste.
2.3 Terceira linha de orçamento: alertas de saldo da conta
A documentação de alertas de saldo da APIYI deixa claro que o alerta é uma notificação e não bloqueia requisições. Quando o saldo cai abaixo do limite, o alerta envia a mensagem ao responsável, que decide se recarrega, pausa a entrada de testes ou investiga tráfego anômalo.
Duas recomendações ao usar essa camada:
- Defina o limite do alerta com base no “consumo máximo durante o tempo entre a detecção e o tratamento”; não escolha um número inteiro aleatório.
- O alerta precisa estar associado a uma ação de tratamento concreta, por exemplo, deixar escrito no manual de plantão: “ao receber o alerta, primeiro feche a entrada de cadastro para testes”. Um alerta que só notifica, sem ação seguinte, é inútil.
3 Um ledger de concorrência hipotético: da reserva atômica à reconciliação
Esta seção apresenta um design ilustrativo. As estruturas de tabela, os preços e os números são todos hipotéticos, servem apenas para explicar o fluxo e não representam dados medidos de nenhum sistema. O fluxo tem cinco etapas:
Verificação e reserva atômica → servidor trava o model e a escala → envia a requisição
→ liquidação / tratamento de falha → correção por reconciliação offline

3.1 Estrutura de tabelas e estados do ledger de orçamento
O design ilustrativo tem duas tabelas: budgets registra o limite, o valor já gasto e o valor já reservado de cada usuário e do pool de testes; reservations registra cada reserva e o seu estado.
| Estado da reserva | Significado | Impacto no “saldo disponível” |
|---|---|---|
| reserved | Já reservado, requisição em andamento | Ocupa o valor estimado |
| settled | Usage real obtido, já liquidado | Passa a ser gasto e libera a diferença |
| released | Confirmado que a requisição não foi executada | Libera o valor total |
| unknown | Timeout, desconexão, custo desconhecido | Continua ocupando, aguardando reconciliação |
O saldo disponível é calculado como limit - spent - reserved, em que reserved inclui as reservas no estado unknown.
3.2 Verificação atômica e reserva: evitar que requisições concorrentes passem ao mesmo tempo
O ponto crucial é combinar “verificar” e “ocupar” em uma única instrução de atualização condicional, deixando o banco de dados garantir a atomicidade:
-- Exemplo: só ocupa quando há saldo suficiente, retorna o número de linhas afetadas
UPDATE budgets
SET reserved = reserved + :estimate
WHERE owner_id IN (:user_id, :pool_id)
AND limit_amount - spent - reserved >= :estimate;
-- O número de linhas afetadas deve ser igual a 2 (usuário e pool ambos com sucesso); caso contrário, reverta a transação e rejeite a requisição
O valor estimado deve usar o limite superior: multiplicar a quantidade de tokens de entrada pelo preço de entrada, e somar max_tokens multiplicado pelo preço de saída. O consumo real costuma ficar abaixo desse valor, e basta devolver a diferença na liquidação. Melhor reservar um pouco a mais do que a menos.
3.3 Bloqueio no servidor do model e da escala da tarefa
Os parâmetros de estimativa usados na reserva precisam ser exatamente iguais aos parâmetros da requisição realmente enviada. O código de exemplo é o seguinte:
ALLOWED_TRIAL_MODELS = {"trial-model-a"} # Exemplo: modelos liberados para o teste
MAX_OUTPUT_TOKENS = 1024 # Exemplo: limite imposto pelo servidor
MAX_INPUT_TOKENS = 8000
def build_trial_request(user_input, requested_model):
model = requested_model if requested_model in ALLOWED_TRIAL_MODELS \
else "trial-model-a"
input_tokens = count_tokens(user_input)
if input_tokens > MAX_INPUT_TOKENS:
raise InputTooLarge()
estimate = price_in(model) * input_tokens \
+ price_out(model) * MAX_OUTPUT_TOKENS
return model, MAX_OUTPUT_TOKENS, estimate
O max_tokens e o model enviados pelo frontend são apenas valores de referência; a decisão final é a do servidor.
3.4 Envio da requisição, liquidação e tratamento de falhas
Antes de enviar a requisição, gere um ID de requisição único e grave-o no registro de reserva, para facilitar a correspondência posterior nos logs. Depois que a requisição retorna, há três casos a tratar:
- Sucesso com
usagedisponível: calcule o valor com base no uso real,spent += actual,reserved -= estimate, e mude o status da reserva para settled. - Falha que claramente não foi executada: por exemplo, falha de validação de parâmetros ou falha de autenticação — erros que confirmam que a requisição não entrou na cobrança. Nesse caso, libere a reserva e mude o status para released.
- Timeout ou conexão interrompida: a requisição pode já ter sido executada no upstream e gerado custo, só que o resultado não voltou. Aqui, não trate o custo como zero: registre o status como unknown e mantenha a reserva ocupada.
O terceiro caso é o mais propenso a erro. Se você simplesmente libera a reserva no timeout, é como apagar do livro-caixa um custo que pode já ter ocorrido. Em períodos de alta concorrência e alta taxa de timeout, esse erro se acumula continuamente.
3.5 Conciliação offline: corrigir unknown e desvios de estimativa
A consulta de logs do APIYI oferece exportação incremental, e a documentação deixa claro que ela se destina à conciliação offline — não serve como base para liberar requisição por requisição. Por isso, a conciliação deve ser feita como tarefa agendada:
- Busque os logs incrementais desde a última conciliação e faça a correspondência com a tabela
reservations, por ID de requisição ou por janela de tempo. - Para as reservas
unknownencontradas nos logs, mude o status para settled usando o valor real do log; aquelas que continuam sem registro após a janela de tempo combinada devem ser marcadas como released. - Levante a distribuição dos desvios entre “valor estimado e valor real”. Se o valor real costuma ficar próximo ou até ultrapassar o estimado, vale revisar a fórmula de estimativa da seção 3.3.
O resultado da conciliação também é insumo para a terceira linha de orçamento: se o total do livro-caixa e o consumo real da conta continuam sem bater, isso por si só já é um sinal de que alguém precisa investigar manualmente.

4 Verificação de lançamento das linhas de orçamento e mensagens amigáveis para cota insuficiente
4.1 Lista de verificação para lançamento das três linhas de orçamento
| Item de verificação | Linha de orçamento | Como validar |
|---|---|---|
| A reserva do usuário e a do pool são concluídas na mesma transação | Primeira linha | Executar teste de carga com requisições concorrentes e confirmar que gasto + reserva não excede o limite |
| model, max_tokens e comprimento da entrada são determinados pelo servidor | Primeira linha | Adulterar parâmetros do frontend e confirmar que não têm efeito |
| Requisições com timeout são registradas como unknown e mantêm a reserva ocupada | Primeira linha | Injetar falha de timeout e verificar o estado do livro-razão |
| A tarefa de reconciliação é executada periodicamente e trata os unknown | Primeira linha | Verificar os logs de reconciliação e a transição de estados |
| A chave de teste é independente e sua cota é ligeiramente maior que o orçamento do pool | Segunda linha | Conferir a configuração da chave e o valor do orçamento do pool |
| A lista de permissões de modelos da chave de teste contém apenas os modelos de teste | Segunda linha | Invocar com um modelo fora da lista de permissões e confirmar que a chamada é rejeitada |
| O script de redefinição da cota diária existe e tem monitoramento | Primeira e segunda linhas | Verificar o histórico de execução da tarefa agendada |
| O limite de alerta de saldo corresponde ao manual de tratamento | Terceira linha | Simular uma vez o fluxo do alerta até o fechamento da entrada |
4.2 Mensagens ao usuário quando a cota é insuficiente
Quando a reserva falha, o aplicativo deve retornar um erro de negócio explícito; não deixe a requisição chegar ao gateway para só então reportar um erro difícil de entender. A mensagem deve incluir três informações:
- O que aconteceu: por exemplo, “a cota de teste de hoje acabou” ou “as vagas de teste atuais estão esgotadas”. Cota insuficiente do usuário e pool de teste cheio devem ser informados separadamente.
- Quando será restabelecido: se houver cota diária, informe o horário de redefinição; se a cota for de uso único e tiver acabado, explique as opções de upgrade disponíveis.
- Estado atual: é possível mostrar a cota restante, mas com base no saldo disponível no livro-razão, incluindo a dedução das reservas em andamento, para evitar a situação de “mostrar saldo disponível e ainda assim recusar a requisição”.
Depois de concluir as verificações acima, dá para validar todo o conjunto de linhas de orçamento de um jeito simples: simular um pico de concorrência combinado com timeout na origem e confirmar que, no livro-razão, “gasto + reservas em andamento” nunca fica abaixo do consumo real após a reconciliação, e que o consumo da chave de teste não ultrapassa de forma significativa a sua cota. Se as duas condições forem atendidas, as três linhas de orçamento só então estarão realmente funcionais.
Referências
- Documentação de gerenciamento de tokens da APIYI: explicação sobre limite flexível,
remain_quota, redefinição diária e lista de modelos permitidos- Link:
docs.apiyi.com/api-capabilities/token-management
- Link:
- Explicação da cota de pré-dedução da APIYI: mecanismo de pré-dedução estimada e liquidação posterior
- Link:
docs.apiyi.com/faq/pre-deduction-quota
- Link:
- Explicação dos alertas de saldo da APIYI: os alertas apenas notificam, não bloqueiam
- Link:
docs.apiyi.com/faq/balance-alerts
- Link:
- Documentação de consulta de logs da APIYI: exportação incremental e conciliação offline
- Link:
docs.apiyi.com/api-capabilities/log-query
- Link:
- OWASP API Security Top 10 2023: API4 Unrestricted Resource Consumption
- Link:
api-security.owasp.org/editions/2023/en/0xa4-unrestricted-resource-consumption/
- Link:
Em todas as coisas, a preparação leva ao sucesso; sem preparação, leva ao fracasso. — Livro dos Ritos · Zhongyong
