Os limites de consumo em APIs PHP protegem a disponibilidade e o custo do serviço, mas uma política mal projetada pode interromper integrações legítimas. Para acertar, não basta definir um número de solicitações por minuto: é preciso identificar quem consome, qual operação executa, que recurso está em risco e como o tráfego real se comporta.
Um projeto eficaz combina limites adequados ao padrão de uso, contadores consistentes entre instâncias e respostas que permitam ao consumidor se recuperar. Também exige observar o efeito das regras antes de torná-las mais rigorosas, especialmente quando vários clientes compartilham credenciais ou dependem de recursos comuns.
Diferencie taxa, cota e concorrência
Esses controles protegem contra problemas distintos e não são intercambiáveis:
- Taxa de solicitações: limita quantas solicitações são aceitas em um intervalo curto. Ajuda a conter rajadas ou tráfego contínuo que sobrecarrega a aplicação.
- Cota acumulada: limita o consumo total durante um período maior, por exemplo, uma quantidade de operações por dia ou ciclo de faturamento. Serve para controlar o uso contratado ou o acúmulo de cargas caras.
- Concorrência: limita quantas operações estão em execução ao mesmo tempo. É útil quando cada operação pode ocupar workers, conexões ou recursos por muito tempo.
Um cliente pode respeitar uma taxa e, ainda assim, acumular muitas operações longas simultâneas; também pode fazer poucas solicitações que consumam uma cota diária cara. Defina o controle com base no risco que deseja reduzir e, se forem necessários vários, especifique como interagem e qual é aplicado primeiro.
Decida qual identidade e recurso você vai limitar
A chave do limite deve representar uma unidade de consumo que faça sentido operacional. Dependendo do produto, pode ser uma credencial, um usuário, uma organização, uma aplicação cliente, uma rota ou uma combinação desses elementos. Limitar apenas por endereço IP pode penalizar redes compartilhadas e não distingue bem os consumidores autenticados; um IP pode servir como sinal complementar para tráfego anônimo ou controles de segurança.
Para clientes autenticados, convém vincular a política a uma identidade estável e aplicar isolamento entre organizações. Uma credencial compartilhada por vários sistemas pode ocultar quem gera uma rajada: sempre que possível, use credenciais separadas ou adicione dimensões que permitam atribuir o consumo. Evite incluir segredos sem transformação em chaves de contadores ou registros.
Nem todas as rotas têm o mesmo custo. Uma consulta simples e uma exportação extensa não deveriam necessariamente consumir o mesmo orçamento. Você pode atribuir pesos ou políticas diferentes a operações caras, desde que o critério seja compreensível e consistente para os consumidores. Verifique também os limites do serviço: uma API pode receber poucas solicitações e, ainda assim, sobrecarregar uma dependência compartilhada, como um banco de dados ou um provedor externo.
Escolha janelas que reflitam o padrão de uso
Uma janela fixa é simples de explicar, mas pode permitir uma rajada no fim de um intervalo, seguida de outra no início do próximo. Uma janela deslizante reduz esse efeito, em troca de mais trabalho de armazenamento e processamento. Um sistema de tokens permite rajadas limitadas e controla a taxa média; é útil quando o tráfego legítimo chega em ondas. A escolha depende do padrão de consumo e da precisão necessária.
Não confunda um pico legítimo de atividade com abuso. Cargas programadas, sincronizações no início do expediente ou novas tentativas após uma interrupção podem concentrar solicitações. Se o produto permitir rajadas, defina explicitamente seu tamanho e quanto tempo o orçamento leva para se recuperar. Para operações longas, limite também a concorrência ou aplique controle de admissão antes de ocupar recursos escassos.
As novas tentativas do cliente também importam. Se uma resposta temporária provocar novas tentativas imediatas, o limite pode agravar o pico. Recomende backoff progressivo, idealmente com variação aleatória, e defina se operações repetidas com a mesma chave de idempotência contam como novas solicitações ou como uma repetição segura.
Coordene contadores quando o PHP for executado em várias instâncias
Um contador armazenado apenas na memória do processo pode funcionar em uma instância, mas perde consistência quando o tráfego é distribuído entre várias. Cada servidor pode aceitar uma parte do limite e, no total, excedê-lo. Em implantações com várias instâncias, o estado deve ser coordenado por meio de um armazenamento compartilhado ou de um mecanismo equivalente com operações atômicas apropriadas.
Projete também o comportamento diante de falhas no sistema de contadores. Se ele ficar indisponível, rejeitar todas as solicitações pode interromper clientes legítimos; aceitar todas pode expor uma dependência crítica. A decisão depende do risco da rota: pode ser razoável falhar de maneira diferente para uma consulta de baixo impacto e para uma operação que gera custos elevados. Documente o critério e alerte sobre degradações.
Evite chaves de contador genéricas demais, que misturem organizações ou rotas, e fragmentadas demais, que dificultem controlar o consumo total. Defina expiração e limpeza do estado para que as chaves temporárias não se acumulem indefinidamente. Verifique se as mudanças de configuração não reiniciam nem duplicam contadores de forma inesperada.
Comunique a rejeição como parte do contrato da API
Quando um limite for atingido, retorne um status HTTP coerente com o contrato da API — normalmente 429 Too Many Requests para uma limitação de taxa — e um corpo estruturado que identifique o tipo de limite sem revelar informações internas. Se a operação for rejeitada por outro motivo, não use esse status de forma enganosa.
Inclua orientações úteis para a recuperação, como o momento estimado para tentar novamente ou os dados de limite e consumo definidos pelo contrato. Se enviar Retry-After, certifique-se de que ele represente um tempo de espera válido. Mantenha respostas consistentes entre rotas e evite expor contadores de outros clientes. Os consumidores devem conseguir distinguir uma rejeição temporária de erros de autenticação, validação ou disponibilidade.
Observe o impacto e ajuste com base em evidências
Registre solicitações aceitas e rejeitadas, a identidade ou o segmento do cliente de forma segura, a rota, a política aplicada e o motivo. Meça também a latência, a concorrência e a pressão sobre dependências relevantes. Não armazene credenciais nem dados pessoais desnecessários; use identificadores protegidos ou agregados quando forem suficientes para a análise.
Um aumento nas rejeições não demonstra, por si só, que o limite seja rigoroso demais. Procure padrões: clientes afetados, horários, rotas, duração das operações e novas tentativas posteriores. Investigue sinais de falsos positivos, como rejeições concentradas em organizações com credenciais compartilhadas ou em tarefas programadas. Ajuste uma variável por vez e mantenha uma forma de reverter a mudança.
Implemente a política gradualmente
Antes de aplicar um limite, avalie a política com dados de uso e teste cenários representativos. Se a arquitetura permitir, registre quais solicitações teriam sido rejeitadas sem bloqueá-las; essa observação não substitui os testes de carga nem garante que os dados históricos antecipem todos os picos.
- Defina o risco que deseja controlar e se o caso exige taxa, cota, concorrência ou uma combinação.
- Atribua limites por identidade e recurso e verifique o isolamento entre usuários e organizações.
- Teste rajadas, operações lentas, novas tentativas, credenciais compartilhadas e falhas no armazenamento de contadores.
- Verifique se várias instâncias aplicam o limite de forma coordenada e se o estado temporário é limpo.
- Valide a resposta de rejeição, as orientações para tentar novamente e a compatibilidade com os consumidores atuais.
- Monitore rejeições, latência e dependências; comunique mudanças que possam afetar as integrações.
Os limites de consumo em APIs PHP devem proteger tanto a plataforma quanto a continuidade dos clientes. A melhor política não é a mais rigorosa, mas aquela que controla o risco com regras que permitam atribuir o consumo, respostas previsíveis e evidências suficientes para corrigir efeitos indesejados.
