Paginação com cursor na API

Resposta curta

Paginação com cursor reduz duplicidade e perda de dados quando comparada a paginação por offset em listas grandes.

Exemplo de loop

let cursor: string | null = null;

while (true) {
  const response = await fetch("https://api.orbioapi.com.br/v1/accounts/search", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.ORBIO_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      spec,
      limit: 100,
      cursor,
    }),
  });

  const payload = await response.json();
  const nextCursor = payload.next_cursor ?? null;

  await processPageAndCheckpoint({
    pageCursor: cursor,
    nextCursor,
    accounts: payload.accounts,
  });

  if (!nextCursor) {
    break;
  }

  cursor = nextCursor;
}

Boas práticas

• Grave checkpoint e efeitos colaterais no mesmo commit durável.
• Trate paginação e validação de dados em camadas separadas.
• Sempre registre snapshot usado na consulta.
• Defina timeout e retry com limites explícitos.

Limitações

• Não é o melhor caminho para extrações muito grandes e recorrentes.
• Sem checkpoint, qualquer falha pode obrigar releitura integral.
• Cursor antigo pode ficar inválido após mudanças fortes de contexto.

Erros comuns

• Avançar next_cursor fora de uma operação idempotente ou atômica.
• Mudar filtros no meio do loop.
• Ignorar métricas de latência e throughput por ciclo.