- Existem 3 padrões comuns: page/limit, cursor (after/since) e link para próxima página (next).
- Loop sem critério de parada é o principal motivo de automação travada e custos inesperados.
- Idempotência + checkpoint (estado salvo) evitam duplicar registros em falhas e reexecuções.
- Rate limit e backoff precisam fazer parte do desenho, não do “conserto” depois.
1) Identifique o tipo de paginação da API (antes de montar o fluxo)
Leia a documentação do endpoint e procure por: parâmetros page/limit (ou offset), campos de cursor (next_cursor, after, since), ou um link next/links. Se não houver doc clara, teste uma requisição e inspecione a resposta: APIs boas sempre devolvem o “como continuar” (cursor, next ou total/offset).
2) Escolha um “checkpoint” de estado (para não reprocessar)
Defina o que será salvo entre execuções: cursor, último ID, última data (since) ou combinação. Guarde isso em um local persistente (banco, planilha, KV, tabela interna, etc.). Sem checkpoint, qualquer erro no meio obriga a recomeçar do zero — e aí aparecem duplicidades.
3) Modele o loop com critério de parada explícito
Critérios de parada típicos: resposta veio vazia, não existe next cursor, ou o next é igual ao atual (proteção anti-loop). Também vale limitar por um máximo de páginas por execução para proteger sua operação quando a API “enlouquecer” e começar a devolver paginação inconsistente.
4) Aplique rate limit e retries com backoff
Mesmo que seu volume seja baixo hoje, automatização acumula. Trate HTTP 429 e 5xx com retry e backoff (idealmente com jitter). Se a API devolver cabeçalhos de rate limit, respeite. Se não devolver, use um intervalo conservador entre páginas.
5) Processe em lotes pequenos e confirme antes de avançar o cursor
Não avance o cursor/checkpoint antes de concluir o processamento do lote atual. Se você salvar o cursor “adiantado” e cair no meio, você perde registros (falha silenciosa). Se salvar “atrasado”, você duplica — por isso idempotência (por ID único) é a rede de segurança.
6) Faça deduplicação e idempotência por chave
Escolha uma chave única do registro (id, email, number, etc.) e garanta que sua escrita no destino seja idempotente (upsert, merge, ou verificação antes de inserir). Em integrações com CRM/planilhas, a regra prática é: se dá para “atualizar se existir”, use isso.
7) Registre logs úteis (não só ‘deu erro’)
Guarde pelo menos: página/cursor atual, tamanho do lote, contagem processada, tempo por página, e o motivo de parada. Isso torna depuração e auditoria muito mais rápidas quando o endpoint muda comportamento.
Os 3 tipos de paginação que você vai encontrar (e como reconhecer)
Paginação não é detalhe: ela define o formato do seu loop e como você salva estado.
Na prática, quase tudo cai em um destes três padrões. O problema é que cada um tem armadilhas diferentes (offset que “pula” registros, cursor que expira, next que muda).
| Tipo | Como vem na API | Prós | Riscos comuns |
|---|---|---|---|
| page/limit (ou offset/limit) | Você manda page=1&limit=100 (ou offset=0&limit=100) | Simples de entender; bom para relatórios | Offset pode ficar lento em bases grandes; dados mudando podem causar duplicação/pulos |
| cursor (after/since/next_cursor) | Resposta traz next_cursor/after; você usa isso na próxima chamada | Mais estável em dados grandes; costuma ser mais performático | Cursor pode expirar; se salvar errado, você perde a posição |
| link para próxima página (next) | Resposta traz um URL next (às vezes em links[]) | Você só segue o next; menos chance de montar query errada | Next pode vir null; pode repetir se a API tiver bug — precisa anti-loop |
Blueprint de fluxo (agnóstico): buscar página → processar → salvar checkpoint → repetir
Se você quer um modelo mental que funciona no n8n, Make e Zapier, use este: o loop nunca é “buscar tudo”; é “buscar um lote, processar, confirmar, e só então avançar”.
Esse desenho reduz dois problemas clássicos: duplicidade em reexecução e perda de registros quando cai no meio.
- Entrada: cursor/page atual (do checkpoint) + parâmetros fixos (limit, filtros).
- Requisição: chama a API e recebe items + ponteiro do próximo passo (next cursor/next link).
- Processamento: valida, transforma e grava (idealmente com upsert).
- Confirmação: apenas após gravar, salva checkpoint com o próximo ponteiro.
- Parada: se items vier vazio, ou next inexistente, ou atingiu limite seguro de páginas.
Como isso aparece no n8n (sem depender de nó específico)
No n8n, o loop pode ser montado de várias formas (nós de loop, divisão de itens, ou controle com variáveis). O ponto não é o nome do nó — é ter um estado (checkpoint) e um critério de parada.
Dica editorial: quando alguém diz “meu workflow está em loop infinito”, quase sempre faltou comparar o cursor atual com o próximo, ou faltou parar quando a lista veio vazia.
- Use um nó HTTP para buscar a página/lote.
- Extraia items e o next (cursor/link).
- Processe items em sequência ou com concorrência controlada (se a API permitir).
- Salve o next em um armazenamento persistente.
- Se next não existir (ou items vazio), finalize.
Como isso aparece no Make (cenários): iterator, agregação e controle de repetição
No Make, a tentação é montar um cenário que “vai indo” sem guardar estado. Funciona… até falhar, e aí você não sabe onde estava.
O caminho mais estável é tratar a paginação como uma sequência de ciclos, cada um com um lote pequeno e checkpoint claro.
- Módulo HTTP: request do lote atual.
- Iterator: percorre items do lote (quando a resposta vem como array).
- Persistência do checkpoint: gravar cursor/page em algum lugar externo ao cenário.
- Repetição: continuar enquanto houver next; parar quando não houver.
Erros reais que quebram paginação (e como blindar)
Paginação dá errado menos por complexidade e mais por detalhes: um campo que muda, um cursor que volta, um endpoint que começa a ordenar diferente.
Você se protege com três travas: anti-loop, limite de páginas por execução e idempotência por chave.
- Anti-loop: se next == current, pare e alerte (isso evita rodar para sempre).
- Limite seguro: defina máximo de páginas por execução (ex.: 200 páginas) e continue na próxima rodada com checkpoint.
- Ordenação: se a API permitir, fixe sort (ex.: por created_at asc) para reduzir instabilidade.
- Dados mutáveis: em page/offset, registros inseridos no começo podem “empurrar” os demais; cursor costuma ser melhor.
- Timeout: prefira lotes menores e mais ciclos, em vez de uma execução gigante.
Perguntas frequentes
Paginação por offset/limit é “ruim”?
Como evitar duplicar registros quando a automação reprocessa uma página?
Como sei que cheguei no fim da paginação?
E se a API responder 429 (rate limit) no meio do loop?
Leia também
Rate limit, retry e backoff: como parar de quebrar automação em API (n8n, Make, Zapier)
Guia direto para lidar com rate limit (429), retries e backoff em automações com APIs. Aprenda padrões práticos para n8n, Make e Zapier e evite falhas intermitentes, duplicidades e banimentos.
Ler →
Como fazer idempotência em automações com webhook (e parar de duplicar pedidos, notas e leads)
Guia direto para aplicar idempotência em automações com webhook: chaves idempotentes, deduplicação, banco/planilha, retries e boas práticas para n8n/Make/Zapier.
Ler →
Webhook ou polling em automações: como escolher (sem perder eventos e sem estourar limites)
Guia direto para decidir entre webhook e polling: latência, confiabilidade, custo por execução, rate limit e como evitar duplicidades. Inclui tabela e checklist prático.
Ler →
Como escrever um “spec” de automação (workflow) que não quebra na primeira semana
Aprenda a documentar um workflow antes de construir: gatilho, dados, regras, erros, idempotência, logs e testes. Modelo prático de spec para n8n, Make e Zapier, com tabela e checklist.
Ler →