Rate Limits, Paginação e Idempotência na API de Assinatura

Uma integração que funciona no ambiente de testes nem sempre sobrevive ao volume de produção. Picos de tráfego esbarram em rate limits, retentativas mal feitas geram cobranças e assinaturas duplicadas, e a listagem de milhares de transações se torna lenta e inconsistente. Este guia técnico reúne os três pilares que separam um protótipo de uma integração robusta com uma API de assinatura digital: rate limits, idempotência e paginação.

Se você já domina os fundamentos descritos no nosso guia da API de assinatura digital e quer levar sua integração para produção, este artigo entra no detalhe operacional que faz a diferença em escala. Vamos cobrir o tratamento de erros 429, o header Retry-After, backoff exponencial com jitter, idempotency keys para reenviar POSTs com segurança e paginação por cursor para varrer grandes coleções.

O conteúdo é agnóstico de linguagem — os exemplos usam cURL e pseudocódigo em JavaScript/Python —, mas se aplica diretamente a quem usa nossos SDKs oficiais ou chamadas REST puras. Para um panorama do tratamento de falhas em geral, vale combinar esta leitura com o artigo sobre códigos de erro e tratamento de falhas na API.

O que são rate limits e por que eles existem

Rate limit é o teto de operações que um cliente pode realizar dentro de uma janela de tempo. Esses limites protegem a plataforma contra abuso, garantem qualidade de serviço para todos os clientes (evitando que um único integrador monopolize a capacidade) e funcionam como uma camada de defesa contra ataques de negação de serviço.

No SignDocs, o mecanismo principal não é um teto de requisições por segundo, e sim cotas de negócio por tenant, com janelas diária e mensal, contadas por tipo de operação — criação de transações e sessões de assinatura têm sua cota; a verificação de PDFs tem cota própria. Os valores são dimensionados no plano sob medida contratado com o time comercial, com possibilidade de franquia adicional (overage) na janela mensal.

Camadas típicas de limite

Headers de rate limit

APIs bem projetadas expõem o estado da sua cota em headers de resposta, permitindo que você se adapte antes de bater no teto. Os mais comuns são:

• RateLimit-Limit: o total permitido na janela atual.
• RateLimit-Remaining: quanto ainda resta na janela.
• RateLimit-Reset: segundos até a janela reiniciar.
• Retry-After: enviado junto com o 429, indica quantos segundos esperar antes de tentar de novo.

O SignDocs usa a forma padronizada sem o prefixo X- (draft do IETF adotado pelas APIs modernas). Um cliente bem comportado monitora RateLimit-Remaining e, ao perceber que está chegando perto de zero, reduz o ritmo de envio proativamente em vez de esperar pelo erro.

Tratando o erro 429 com Retry-After e backoff

Quando você ultrapassa o limite, a API responde com 429 Too Many Requests. A resposta correta nunca é repetir a chamada imediatamente — isso só agrava a sobrecarga. O fluxo recomendado é: ler o Retry-After, aguardar pelo menos esse tempo e então retomar com backoff exponencial e jitter.

Anatomia de uma resposta 429

Backoff exponencial com jitter

O backoff exponencial aumenta o intervalo entre tentativas a cada falha consecutiva (1s, 2s, 4s, 8s...). O jitter — um componente aleatório somado ao intervalo — evita que vários clientes que falharam ao mesmo tempo tentem novamente em sincronia, fenômeno conhecido como thundering herd. Quando o 429 traz Retry-After, esse valor é o piso mínimo de espera.

Idempotência: reenviando POSTs com segurança

Aqui mora o problema mais sutil de toda integração de pagamento ou assinatura: o que fazer quando um POST dá timeout e você não sabe se ele foi processado? Se você simplesmente reenviar, corre o risco de criar duas transações, dois envelopes ou duas cobranças para o mesmo evento de negócio. Se não reenviar, pode perder a operação. A solução é a idempotência.

Uma requisição é idempotente quando executá-la várias vezes produz o mesmo efeito de executá-la uma única vez. GET e DELETE já são naturalmente idempotentes; POST não é — e é exatamente por isso que precisamos de um mecanismo explícito.

Como funciona a idempotency key

1. Seu cliente gera um identificador único — tipicamente um UUID v4 — antes de enviar o POST.
2. Esse valor vai no header X-Idempotency-Key da requisição.
3. A API armazena a chave junto com o resultado da primeira execução bem-sucedida.
4. Se a mesma chave chegar de novo (uma retentativa), a API não cria um novo recurso: ela devolve a resposta original memorizada.

O ponto crucial é gerar a chave uma vez por operação de negócio e reutilizá-la em todas as retentativas daquela operação. Gerar uma chave nova a cada tentativa anula completamente a proteção.

Exemplo: criando uma signing session de forma idempotente

O endpoint POST /v1/signing-sessions da Assinatura Expressa cria uma sessão de assinatura em uma única chamada. Veja como protegê-lo com uma idempotency key via cURL:

Repare que usamos o host de homologação api-hml.signdocs.com.br (forma com hífen). É o ambiente correto para testar fluxos de retry sem afetar produção — lembrando que as entidades de homologação têm TTL de 7 dias. Para um passo a passo completo em cURL, consulte o guia integrar assinatura digital com cURL/REST.

Respostas possíveis ao reusar uma chave

Paginação: listando transações em escala

Endpoints de listagem — como GET /v1/transactions ou a consulta de eventos — nunca devolvem todos os registros de uma vez. Eles paginam o resultado. Entender o modelo de paginação correto evita varreduras lentas, inconsistentes e custosas em cota.

Offset vs. cursor

Existem dois modelos predominantes:

• Offset/limit: você pede a página N com ?limit=50&offset=100. Simples, mas degrada em grandes volumes e é instável: se registros forem inseridos durante a varredura, itens podem ser pulados ou repetidos.
• Cursor (keyset): cada resposta devolve um ponteiro opaco (no SignDocs, nextToken) que aponta para onde a próxima página começa. É estável mesmo com inserções concorrentes e tem desempenho constante — é o modelo da API.

Anatomia de uma resposta paginada por cursor

Para buscar a próxima página, repita a chamada passando o token: GET /v1/transactions?limit=50&nextToken=eyJQSyI6.... Quando a resposta vier sem nextToken, você chegou ao fim da coleção. Os filtros aceitos incluem status, userExternalId, documentGroupId, startDate e endDate.

Loop de paginação completo

O padrão correto para varrer uma coleção inteira é um laço que segue o cursor até esgotá-lo. Veja em Python, já combinando paginação com respeito ao rate limit:

Consistência: o que esperar dos dados retornados

APIs distribuídas frequentemente operam com consistência eventual em algumas leituras. Isso significa que, logo após criar uma transação, uma consulta de listagem pode levar alguns instantes para refleti-la. Entender esse comportamento evita bugs sutis.

• Leitura após escrita: consultar um recurso diretamente pelo seu ID (GET /v1/transactions/{id}) logo após criá-lo tende a ser consistente. Já varrer a listagem esperando vê-lo imediatamente pode falhar por replicação em andamento.
• Ordenação estável: ao paginar por cursor, a ordem é garantida pela chave de ordenação (normalmente data de criação). Não dependa de ordenação implícita em paginação por offset.
• Fonte da verdade para eventos: para acompanhar mudanças de estado em tempo real, prefira webhooks de eventos a polling de listagem. Use a listagem paginada como reconciliação periódica, não como mecanismo primário.

Para entender como cada estado de uma transação se conecta ao próximo, e em que ponto cada leitura se torna confiável, vale revisar o fluxo transacional completo da API, que detalha o ciclo de vida de ponta a ponta.

Checklist de integração resiliente

Antes de promover sua integração para produção, valide que ela atende a estes pontos. Se você está começando agora, o quickstart de 5 minutos cobre o caminho inicial; este checklist é o que torna a integração à prova de escala:

1. Cache de token: o bearer OAuth2 é reaproveitado e só renovado perto da expiração.
2. Retry seletivo: retentativas apenas para 429 e 5xx, nunca para 4xx de validação.
3. Backoff com jitter: intervalo exponencial com componente aleatório, respeitando Retry-After.
4. Idempotency keys: toda escrita (POST) crítica carrega uma chave única por operação de negócio, reutilizada nas retentativas.
5. Limite de tentativas: um número máximo de retentativas, com falha controlada (dead-letter/alerta) ao esgotá-las.
6. Paginação por cursor: varreduras seguem o nextToken até ele deixar de vir na resposta, com streaming.
7. Filtros no servidor: use parâmetros de filtro em vez de baixar tudo e filtrar localmente.
8. Monitoramento de cota: logue RateLimit-Remaining e alerte quando ele se aproximar de zero recorrentemente.
9. Eventos via webhook: status em tempo real por webhook; listagem como reconciliação.