Limites de requisições (rate limits)
Para manter o serviço estável para todos, o Cord aplica um limite de requisições por IP.
O limite
Há um piso global de aproximadamente 500 requisições por minuto por IP em todas as rotas. Além disso, cada chave de API tem o próprio limite: 600 requisições por minuto para uma chave secreta (sk_) e 120 por minuto para uma chave publicável (pk_, mais restrita porque fica exposta no navegador). Todos são limites por minuto (janela móvel de 60 segundos), não por segundo. Para integrações B2B normais (sincronizar catálogos, criar orçamentos, ler recebíveis), há folga de sobra.
À parte do limite de requisições, o plano da sua assinatura inclui uma cota mensal de chamadas à API; ultrapassá-la também responde 429, mas com code: "api_quota_exceeded" em vez de um problema de velocidade — a solução, nesse caso, é fazer upgrade do plano, não tentar de novo mais devagar.
Como tratar o 429
Se você ultrapassar o limite de requisições, o Cord responde 429 Too Many Requests com um header Retry-After: 60 (segundos). A sua aplicação deve tratá-lo com backoff exponencial:
- Se receber um 429, espere e tente de novo (respeite o
Retry-After, se vier). - Se falhar de novo, dobre a espera: 1s, 2s, 4s, 8s…
- Defina um máximo de tentativas para não ficar em loop.
Boas práticas: agrupe leituras com paginação (limit/offset) em vez de muitas chamadas pequenas e evite polling agressivo — para saber de mudanças, use Webhooks em vez de consultar em loop.