O Que Quebra Primeiro Quando Ignoramos Limites de API
Uma empresa que executa três integrações simultaneamente – uma sincronização ERP noturna, um Webhook de um sistema de pagamento e um painel externo que busca dados a cada cinco minutos – não falha gradualmente. Ela funciona perfeitamente até ultrapassar um limite, e então cada chamada de API adicional é rejeitada com o código REQUEST_LIMIT_EXCEEDED até o reinício diário. Não há um aviso prévio integrado que evite isso antecipadamente – existe apenas um Dashboard que pode ser consultado, se alguém tiver construído um processo para verificá-lo.
Essa falha difere da maioria das falhas em projetos Salesforce porque não depende de código ruim ou design falho. Ela depende do acúmulo: uma nova integração é sempre construída considerando o status atual, sem verificar quanto do orçamento diário já foi consumido pelos processos existentes. O resultado é que a quinta integração "quebra" as quatro anteriores, embora nenhuma delas tenha sido alterada.
O Mapa de Limites Realmente Relevante
Nem todo Limite existente no Salesforce é igualmente importante para o planejamento de integrações. Aqueles que realmente definem a arquitetura são:
| Tipo de Limite | O que ele mede | Quem ele afeta primeiro |
|---|---|---|
| Requisições de API Diárias | Total de requisições REST/SOAP em 24 horas | Qualquer integração síncrona de alta frequência |
| Batches de Bulk API | Número de Batches abertos/diários | Processos noturnos de Batch que inserem dados históricos |
| Requisições Concorrentes de Longa Duração | Chamadas em execução por mais de 20 segundos simultaneamente | Relatórios pesados ou lógicas complexas de Apex assíncronas |
| Entrega de Platform Event | Volume de eventos por dia por assinatura | Arquiteturas Event-Driven entre Salesforce e sistemas externos |
| Linhas SOQL por Transação | Linhas buscadas em uma única transação (50.000) | Lógica Apex que executa consultas dentro de um loop |
Esta tabela não é uma documentação genérica – é uma ordem de prioridades. Uma organização que planeja uma nova integração deve verificar primeiro as duas primeiras linhas, pois são as que realmente são bloqueadas em produção. Os demais limites afetam principalmente o desempenho, não a disponibilidade.
Orçamento de Chamadas: Como Construí-lo Corretamente
A principal ferramenta para evitar bloqueios não é o monitoramento pós-fato, mas um orçamento predefinido para cada consumidor de API. O princípio é: cada sistema externo, cada Usuário de Integração e cada processo agendado recebe uma alocação definida da cota total, e não "o quanto for necessário".
A construção do orçamento envolve três etapas:
- Mapeamento de Consumidores – Uma lista de todos os processos que chamam a API: integrações externas, Apex Agendado, Data Loader manual, ferramentas de BI. Cada um tem um Usuário de Integração separado para que o consumo possa ser isolado no Event Monitoring.
- Cálculo da Carga com Base no Volume de Negócios, não em Presunção – Quantos registros são processados por dia, quantas chamadas são necessárias por registro (incluindo a busca de Related Lists) e o que acontece nos picos (final de trimestre, Black Friday, fechamento de mês).
- Alocação de Reserva – Não se divide 100% da cota entre os processos existentes. Deixa-se 15%-20% como reserva para processos de emergência, relatórios ad-hoc e manutenção – caso contrário, qualquer pequena adição empurra a organização para uma violação.
Quem deseja aprofundar no design da camada que gerencia esse orçamento em nível de plataforma deve ler o Guia de Arquitetura de CRM, onde é apresentada a divisão entre a camada de integração e a camada de negócios.
REST vs. Bulk: Quando a Transição Compensa
O erro mais comum é usar a API REST normal para tráfego de dados de alto volume, porque é o que é construído primeiro e funciona em Provas de Conceito (PoCs). O problema surge quando o volume aumenta: REST conta cada requisição (até 200 registros em Composite) como uma chamada separada em relação à cota, enquanto Bulk API 2.0 executa lotes de até 10.000 registros e é contabilizado com um custo significativamente menor por registro.
Uma regra prática: se um único processo atualiza mais de 2.000 registros em uma única execução, a transição para Bulk API quase sempre compensa – mesmo que isso signifique alterar o código do consumidor para trabalhar assincronamente com polling no status do Job, em vez de uma resposta imediata. O custo é uma latência maior (minutos em vez de segundos), e, portanto, Bulk não é adequado para processos que exigem decisão em tempo real, como verificação de inventário antes da aprovação de um pedido.
Backoff e Retry: Prevenindo a Auto-Sobrecarga
Quando uma chamada de API falha devido a um bloqueio de limite, a resposta instintiva da maioria das equipes é tentar novamente imediatamente. Este é exatamente o comportamento que transforma um bloqueio temporário em uma falha contínua: se dez processos tentarem novamente no mesmo instante, eles empurram o sistema mais profundamente para o bloqueio, em vez de permitir que ele se recupere.
Um mecanismo de Backoff adequado requer três componentes juntos:
- Exponential Backoff – O tempo de espera entre as tentativas aumenta exponencialmente (por exemplo, 2, 4, 8, 16 segundos), e não permanece constante.
- Jitter – Uma pequena adição aleatória ao tempo de espera, para que processos paralelos não tentem novamente no mesmo segundo e criem uma nova onda de carga.
- Circuit Breaker – Após um certo número de falhas consecutivas (por exemplo, cinco), o processo para de tentar completamente por um período fixo e reporta ao monitoramento, em vez de continuar "batendo na porta".
Sem um Circuit Breaker, um processo que é executado a cada cinco minutos e falha consistentemente continuará a tentar cem vezes por dia e consumir cota apenas para falhas – isso é exatamente o oposto do que o mecanismo deveria prevenir. Detalhes adicionais sobre o tratamento de erros em nível de integração são apresentados em Gerenciamento de Erros de Integração no Salesforce.
Estudo de Caso: Varejo com Três Pontos de Integração
Suponhamos uma rede de varejo de médio porte, com aproximadamente 40 filiais, que opera o Salesforce Service Cloud integrado a um sistema de PDV e um sistema ERP para controle de estoque. Três integrações estão ativas: sincronização de estoque a cada 15 minutos do ERP (cerca de 8.000 itens SKU), um Webhook do PDV para cada transação que falha (cerca de 300 por dia) e um painel externo para o Power BI que busca dados de serviço a cada hora.
No mês em que a rede adicionou um novo programa de fidelidade, uma quarta integração foi inserida: a verificação de pontos de crédito em tempo real do Salesforce a partir de cada caixa, adicionando cerca de 6.000 chamadas por dia. Em duas semanas, a sincronização de estoque começou a falhar por volta das 14:00-15:00, o horário de pico dos caixas. A equipe verificou inicialmente o ERP e pensou que o problema estava lá, mas o log do Salesforce mostrou REQUEST_LIMIT_EXCEEDED exatamente nesse período.
A solução não foi comprar cota adicional, mas sim mudar as prioridades: a verificação de pontos de crédito passou a usar o Platform Cache para resultados que não mudam frequentemente, o que reduziu as chamadas em cerca de 70%, e a sincronização de estoque mudou de REST para Bulk API com execução a cada 30 minutos em vez de 15. O resultado: a mesma cobertura de negócios, consumo de cota 45% menor e uma reserva real para o próximo crescimento.
Riscos e Ações Preventivas Específicas
| Risco | Como ele se manifesta na prática | Ação Preventiva |
|---|---|---|
| Nova integração não verificada em relação ao orçamento existente | Bloqueio aparece apenas após a implantação em produção | Exigência de Revisão de Capacidade (Capacity Review) para toda nova integração antes do Go Live |
| Retry sem Backoff | Bloqueio temporário se torna uma falha de horas | Exponential Backoff com Jitter e Circuit Breaker em todo consumidor de API |
| Uso de REST para grandes volumes | Um único processo consome dezenas de porcento da cota diária | Transição para Bulk API acima de um limite de volume predefinido |
| Ausência de separação de Integration Users | Impossibilidade de saber qual integração consome a cota | Usuário de Integração dedicado para cada sistema externo, monitorado separadamente |
| Falta de reserva no orçamento | Qualquer pequena adição leva à violação | Alocação de 15%-20% da cota como reserva permanente, não atribuída a processos diários |
Checklist Antes de Adicionar uma Nova Integração
- ☐ É conhecido o percentual da cota diária consumido atualmente, por Integration User.
- ☐ O volume de pico (não o volume médio) da nova integração foi verificado.
- ☐ Foi decidido usar REST vs. Bulk API com base no limite de volume, não na conveniência de desenvolvimento.
- ☐ Existe um mecanismo de Backoff com Jitter e Circuit Breaker no código do consumidor.
- ☐ Foi configurado um alerta quando o consumo da cota diária excede 70%.
- ☐ O uso possível de Platform Cache para reduzir chamadas repetidas foi verificado.
- ☐ Há uma reserva de 15%-20% da cota que não foi previamente alocada.
- ☐ Um Proprietário operacional foi definido para receber o alerta, e não apenas um log técnico.
Como Monitorar no Dia a Dia
A medição confiável requer a combinação de três fontes: Event Monitoring (ou Shield Event Monitoring) para o consumo real de API por usuário, Apex Limits no próprio código (Limits.getLimitApiRequests()) para verificação local em tempo de execução, e o Dashboard integrado em Company Information que exibe o consumo versus a cota em nível de organização. Nenhuma das três é suficiente sozinha: a primeira mostra tendências, a segunda previne falhas dentro de um único processo, e a terceira serve como um panorama diário para a equipe de operações.
Uma métrica a ser acompanhada ao longo do tempo não é apenas "quanto foi consumido", mas "qual a taxa de crescimento mensal do consumo" – pois é isso que permite prever quando a organização atingirá o limite, em vez de reagir depois que o bloqueio já ocorreu. Quando há vários sistemas interdependentes, vale a pena examinar também o padrão geral de integração em relação à integração Salesforce com sistemas ERP, e a questão da implementação – Flow vs. Apex – que também afeta a eficiência das chamadas, em Salesforce Flow ou Apex.
Resumo
Os Limites de API do Salesforce não são um problema que se resolve no momento em que é descoberto – eles são uma variável que deve fazer parte de cada decisão de integração desde o primeiro dia. Um orçamento de chamadas documentado por Integration User, uma escolha consciente entre REST e Bulk com base no volume, e um mecanismo de Backoff que previne a auto-sobrecarga – esses três juntos são o que diferencia uma organização que descobre o problema quando já está bloqueada, de uma organização que o vê se aproximando com um mês de antecedência e age a tempo.