Teto de gasto

O teto de gasto limita quanto a organização, ou um projeto, pode gastar em um período de cobrança. Ao chegar no teto, a plataforma bloqueia o crescimento e, se você escolher, desliga o que não é produção e depois a produção, em degraus. O teto vive em Cobrança › Teto de gasto e é diferente do orçamento de Custos e orçamentos: o orçamento só avisa por e-mail, o teto também age.

O teto está disponível nos planos que incluem spending.caps; o teto por projeto exige spending.projectCaps. Sem o recurso no plano, a tela explica e a API responde 403 plan.feature_unavailable. O teto vale para organizações cobradas em reais (409 spending_cap.currency_not_supported em outra moeda).

Quem pode

Ação	Papel
Ver o teto e o histórico	Owner e Admin
Criar, alterar e remover o teto da organização	Owner
Criar, alterar e remover o teto de um projeto	Owner e Admin
Ver o banner "Teto de gasto atingido"	Qualquer membro

Developer e Viewer veem "Acesso negado" na tela do teto, mas recebem o banner global quando o teto é atingido.

O que conta como gasto

• Organização: o total estimado da fatura do período aberto, antes de créditos e impostos. Créditos não reduzem o gasto, porque o teto limita consumo, não caixa. A exceção é o modo saldo (abaixo).
• Projeto: o custo atribuído ao projeto sem a parcela da mensalidade. A mensalidade é paga de qualquer jeito, e o rateio mudaria quando outro projeto consumisse mais, o que tornaria o teto do projeto imprevisível.

O teto da organização precisa ser maior ou igual à mensalidade do plano (400 spending_cap.below_base_price no campo amount). Senão ele nasceria atingido.

Modos

Modo	O teto é
Valor fixo (FIXED)	Um valor em reais por período.
Saldo de créditos (PREPAID_BALANCE, só na organização)	O gasto já coberto mais o saldo de créditos. Ao acabar o saldo, o teto é atingido. Comprar créditos libera na hora.

Com o modo saldo e a recarga automática ligados, o teto só é atingido se a recarga falhar.

Avisos

A plataforma envia avisos ao chegar em 50%, 80% e 100% do teto, uma vez por período e por limiar, e o portal colore a barra de gasto nesses pontos. O aviso de 100% é obrigatório e não pode ser desligado nas preferências de notificação.

Degraus de contenção

Ao atingir 100%, o teto passa para Teto atingido e os degraus valem em ordem:

1. Bloquear crescimento (sempre ligado). Deploy de imagem ou configuração nova, escala para mais instâncias, redimensionamento, aplicações novas, builds (se você marcar Bloquear builds), disparo manual de jobs e funções e autoscaling com máximo maior respondem 423 spending_cap_reached. Rollback, redução, remoção, pausa, leitura, pagamento, recarga e a mudança do próprio teto continuam permitidos. No canvas do ambiente, "Revisar e aplicar" mostra o erro spending_cap_reached para mudanças que aumentam o consumo.
2. Desligar o que não é produção (opcional). Depois da carência (0 a 1440 minutos, padrão 30), as aplicações dos ambientes sem proteção, incluindo previews, vão a zero instância, as funções e os crons são suspensos e os bancos hibernam. O estado anterior de cada recurso fica guardado.
3. Desligar produção (opcional, exige o segundo fator ao ligar). Depois de uma segunda carência (0 a 1440 minutos, padrão 60, contada depois do passo anterior), a produção também vai a zero instância.

Bancos, volumes e armazenamento de objetos não são apagados em nenhum degrau: bancos hibernam preservando o disco e o backup, e volumes e buckets só guardam dados.

O que nunca é apagado

• Nenhum dado. A contenção pausa computação; ela não exclui aplicações, bancos, volumes, buckets, segredos nem configuração.
• O armazenamento continua sendo cobrado durante a contenção, porque os dados continuam lá.
• A organização, os membros e a trilha de auditoria permanecem.

Desvio máximo

O gasto é medido por estimativa e o teto é reavaliado a cada poucos minutos. O consumo chega com o atraso da ingestão de uso, mais o intervalo da avaliação (5 minutos por padrão). Por isso pode haver um pequeno excedente acima do teto: no máximo o consumo da capacidade em execução durante esse atraso, mais o armazenamento, que continua sendo medido durante a contenção. O portal repete esse aviso no cartão do teto.

Como o teto é liberado

O teto volta a Dentro do teto quando:

• você aumenta o teto acima do gasto atual;
• você remove o teto;
• o período vira (o gasto recomeça do zero);
• no modo saldo, uma recarga é confirmada.

Se Retomar automaticamente ao liberar estiver ligado, a plataforma cria uma ação de retomada que devolve cada recurso ao estado anterior à contenção. Um recurso que mudou desde então (removido, ou alterado por você) é pulado e aparece como "Ignorado" no histórico. Organizações suspensas ou desativadas pela plataforma não são religadas pela retomada.

Você também pode usar Retomar agora, que responde 409 spending_cap.still_reached se o gasto ainda passa do teto.

Histórico de ações

Cada cartão do teto lista as últimas ações (contenção de não produção, contenção de produção e retomada) com o resultado por item: Feito, Falhou, Sem suporte (recursos que só guardam dados) ou Ignorado. Uma falha em um item não impede os demais; a ação fica "Falhou em parte" e a administração é avisada.

Pela API

GET    /api/v1/orgs/{orgId}/spending-caps
GET    /api/v1/orgs/{orgId}/spending-caps/status          # banner global, Viewer ou acima
PUT    /api/v1/orgs/{orgId}/spending-caps/organization    # Owner; If-Match ao alterar
DELETE /api/v1/orgs/{orgId}/spending-caps/organization
PUT    /api/v1/orgs/{orgId}/spending-caps/projects/{projectId}
POST   /api/v1/orgs/{orgId}/spending-caps/{capId}/resume

Alterar e remover exigem If-Match com a versão lida (428 sem o cabeçalho, 412 com versão velha). Ligar a contenção de produção responde 401 step_up_required até o segundo fator.