Limites e cotas

A API tem limite de requisições por API key, e algumas operações são processadas de forma assíncrona. Esta página diz quais são os limites, o que a resposta devolve quando você estoura, e em quanto tempo o que é assíncrono termina.

Prévia — ainda não aplicado (17/09/2026)

Nenhum limite desta página é aplicado hoje, e os headers abaixo ainda não chegam nas respostas. Os números são a base inicial, publicada para você dimensionar a integração — eles podem mudar antes de entrar em vigor.

Quando entrarem, entram com aviso prévio, pela política de versionamento.

Como o limite é medido

Por API key. Como a chave já define a instituição, o limite é por integração — duas chaves da mesma organização têm orçamentos independentes.

O limite é uma janela deslizante de um minuto. Não há cota mensal.

Os limites

Operação	Limite inicial
Global, qualquer endpoint	600 requisições/min por chave
POST /crm/events	600 eventos/min por chave
POST /crm/contacts/batch/upsert	10 chamadas/min por chave · 1.000 itens por chamada

Trate como teto, não como meta: dimensione a integração abaixo dele e você nunca vê um 429.

Os headers

Toda resposta traz o estado da sua janela, no formato do padrão HTTP em padronização na IETF — sem prefixo X-:

RateLimit-Limit: 600
RateLimit-Remaining: 587
RateLimit-Reset: 34

Header	O que é
RateLimit-Limit	O teto da janela atual.
RateLimit-Remaining	Quantas requisições sobram nela.
RateLimit-Reset	Quantos segundos faltam para a janela reiniciar. É um intervalo, não um horário — 34 significa "daqui a 34 segundos".

Quando você estoura

429 Too Many Requests, com o mesmo envelope de erro de toda a API e um header dizendo qual limite estourou:

RateLimit-Reset: 18
Workfuse-RateLimit-Reason: global-rate

{
  "status": "error",
  "message": "Limite de requisições excedido. Tente novamente em 18 segundos.",
  "category": "RATE_LIMITS",
  "correlationId": "a43683b0-5717-4ceb-80b4-104d02915d8c"
}

Workfuse-RateLimit-Reason	Significa
global-rate	Você passou do limite global da chave. Reduza o ritmo.
endpoint-rate	Você passou do limite daquele endpoint. Reduza o ritmo naquele endpoint.
batch-size	O lote passou de 1.000 itens. Quebre em lotes menores.

Como tratar

Espere o RateLimit-Reset e repita — é o número de segundos que falta. Três regras que evitam o problema em vez de reagir a ele:

• Backoff exponencial com jitter. Repetir todo mundo ao mesmo tempo depois do reset recria o pico que causou o 429. Some um aleatório ao intervalo.
• Controle o ritmo no cliente, com um token bucket — há biblioteca pronta em qualquer linguagem. Sai mais barato que tratar 429.
• Use o lote. Mil contatos em uma chamada de batch/upsert gastam 1 do seu orçamento; mil chamadas de POST /contacts gastam 1.000 e estouram o minuto.

Processamento assíncrono

Uma operação não termina na resposta:

Operação	Responde	O que significa
POST /crm/contacts/batch/upsert	202 Accepted	O lote entrou na fila.

O 202 diz recebi e vou processar, não pronto. A resposta traz um id para você guardar e citar no suporte:

{
  "batchId": "bat_01J8ZQ7K3M",
  "accepted": 87,
  "receivedAt": "2026-09-17T13:02:11.482Z"
}

Esse id é o handle de consulta. GET /crm/batches/{batchId} devolve o progresso e, ao concluir, o resultado por item, por 30 dias — veja Consultar o lote. Para ser avisado sem fazer polling, assine os webhooks.

Prazo

Até 5 minutos em condição normal, contados do 202. Duas coisas esticam esse prazo, e valem saber:

• A primeira chamada depois de um período ocioso demora mais. O processamento escala a partir de zero, e subir a capacidade entra no tempo.
• Volume grande enfileira. Mandar 50 lotes de uma vez não os processa em paralelo — eles entram na fila e saem no ritmo dela.

A entrega é at-least-once

O mesmo item pode ser processado mais de uma vez. É consequência de ser fila com retentativa, não defeito: uma falha de rede entre o processamento e a confirmação faz a tarefa voltar.

Por isso cada item do lote carrega uma chave de idempotência sua — a propriedade de identidade. É ela que faz o reprocessamento ser inofensivo. POST /crm/events é síncrono (201), e o deliveryId torna o reenvio do mesmo evento inofensivo. É o mesmo papel do Idempotency-Key que você já conhece de outras APIs.

Retentativa

Falha de plataforma retenta sozinha, com backoff exponencial. Recusa de negócio não retenta — um payload inválido vai continuar inválido, e a retentativa só gastaria capacidade. Nos dois casos você não precisa fazer nada: reenviar por conta própria, com a mesma chave de idempotência, é sempre seguro.

Quando um limite muda

Limite que aperta entra com aviso prévio, nunca de um dia para o outro. Limite que afrouxa entra na hora.

Enquanto a API estiver em prévia, os números desta página podem mudar sem aviso — é o que o bloco no topo diz.