Rate limits
A plataforma IDCloud aplica rate limits em todos os contratos. Os limites têm escopo por tenant e dependem do seu nível de contrato — as tabelas abaixo apresentam os padrões típicos.
Os limites exatos são configurados por tenant. Entre em contato com o time de Onboarding para confirmar os limites aplicados à sua conta antes de dimensionar para integrações de alto throughput.
| Endpoint | Limite padrão |
|---|---|
POST /oauth2/token | 60 / minuto |
POST /v1/process (Web & SDK) | 100 / minuto |
GET /client/v1/process/\{id\} | 600 / minuto |
GET /client/v1/process/\{id\}/...document... | 300 / minuto |
POST /processes/v1 (API) | 100 / minuto |
GET /processes/v1/\{id\} | 600 / minuto |
POST /v2/magic-link | 60 / minuto |
GET /v2/history/request | 300 / minuto |
Os limites são aplicados por tenant, janela deslizante.
A plataforma retorna:
HTTP/1.1 429 Too Many Requests
Retry-After: 12
| Header | Significado |
|---|---|
Retry-After | Número de segundos a aguardar antes de tentar novamente. Respeite-o. |
Se Retry-After estiver ausente, use backoff exponencial (1s, 2s, 4s, 8s, …) com limite de 60s.
Cache do access token
O token OAuth2 tem TTL de 1 hora. Não chame POST /oauth2/token por requisição — armazene em cache o token na memória ou em cache distribuído e reutilize-o. Esta única otimização elimina a maior parte da pressão no endpoint de token.
Use webhooks em vez de polling
Assine Webhooks e Eventos para PROCESS_STATE_FINISHED em vez de fazer polling em GET /client/v1/process/\{id\}. Um loop de polling pode facilmente esgotar o orçamento de GET-process em tráfego intenso.
Agrupe buscas de documentos
Se precisar buscar documentos de muitos processos (ex.: reconciliação ao final do dia), distribua as requisições ao longo do tempo em vez de disparar todas em paralelo. O header Retry-After é seu aliado; respeite-o.
Trate bursts na entrada
Se o seu front-end pode gerar bursts (ex.: pico de campanha), aplique rate limit do seu lado antes de chamar a Unico. Descarte ou enfileire requisições acima do orçamento por segundo do seu tenant.
Os rate limits limitam requisições por minuto, mas a plataforma também possui limites de concorrência no nível de infraestrutura. A implicação prática: mesmo que você tenha orçamento para 100 requisições/minuto, disparar todas as 100 no mesmo segundo tem mais chance de ser rejeitado do que distribuí-las ao longo do minuto.
Para integrações de alto throughput, busque um RPS constante em vez de bursts.
A Trully tem suas próprias cotas de entrega para o Webhook V2. Espera-se que o servidor de webhook responda em até 1 minuto; respostas mais lentas são descartadas (o processo do usuário não é afetado). Para processamento consistente, confirme o webhook rapidamente e processe-o de forma assíncrona.
- Autenticação — estratégia de cache do token.
- Webhooks e Eventos — substituindo polling por push.
- Códigos de erro > Política de retry — quando (e quando não) tentar novamente.