Paginação e chaves de idempotência na API da Stripe: starting_after, has_more e a janela de 24 horas

O que é

A referência de paginação da Stripe descreve métodos de listagem que "share a common structure and accept, at a minimum... limit, starting_after, and ending_before," e que usam "cursor-based pagination... Both parameters accept an existing object ID value... and return objects in reverse chronological order". Ela também afirma que os dois parâmetros de cursor "are mutually exclusive." Toda resposta de listagem empacota os resultados como {"object": "list", "data": [...], "has_more": bool, "url": "..."}, com limit de valor padrão 10 e máximo de 100. Além disso, as bibliotecas cliente da Stripe oferecem "auto-pagination helpers to traverse all pages of a list", de modo que raramente é preciso percorrer starting_after manualmente. Para escritas, a referência de idempotência da Stripe explica que o cabeçalho Idempotency-Key permite ao cliente "safely repeat the request without risk of creating a second object or performing the update twice", porque a Stripe "sav[es] the resulting status code and body of the first request... regardless of whether it succeeds or fails". As chaves salvas podem ser removidas quando têm pelo menos 24 horas (uma chave reutilizada depois disso é tratada como uma nova requisição), e uma resposta reproduzida traz Idempotent-Replayed: true. Reutilizar uma chave com parâmetros diferentes é rejeitado: "the idempotency layer compares incoming parameters to those of the original request and errors if they're not the same." Os resultados só são salvos depois que o endpoint começa a ser executado; assim, uma requisição que falhou na validação ou colidiu com outra requisição concorrente pode ser repetida com a mesma chave. A página de limites de taxa da Stripe indica um limite global de 100 requisições por segundo em modo live e 25 em sandbox, 25 por segundo por endpoint, salvo indicação em contrário, e 20 requisições de leitura por segundo para a Search API. Requisições limitadas recebem 429 e um cabeçalho Stripe-Rate-Limited-Reason (global-rate, endpoint-rate, global-concurrency, endpoint-concurrency ou resource-specific). Um 429 sem esse cabeçalho não é um limite de taxa: pode ser um lock_timeout em um objeto que outra requisição mantém bloqueado.

Por que importa

A paginação por deslocamento (offset) não é oferecida em nenhum dos endpoints de listagem v1 da Stripe, portanto qualquer tentativa de calcular um número de página no cliente não funciona. As chaves de idempotência são a forma documentada de tornar um POST repetido (após um timeout ou uma conexão interrompida) seguro, sem risco de criar uma cobrança ou um cliente em duplicidade.

Como aplicar

• Use has_more, e não a quantidade de itens retornados, para decidir se deve buscar outra página; passe o id do último item como starting_after.
• Prefira o iterador de auto-paginação da biblioteca cliente a laços escritos à mão.
• Gere uma chave de idempotência nova (a Stripe sugere um UUID v4) para cada tentativa lógica de escrita, e reutilize a mesma chave apenas ao repetir exatamente a mesma requisição após uma falha de rede.
• Não coloque dados sensíveis nas chaves de idempotência e limite-as a no máximo 255 caracteres, conforme as restrições da Stripe.
• Diante de um 429, faça backoff exponencial com jitter e leia Stripe-Rate-Limited-Reason; nunca aumente a concorrência para compensar. Não faça testes de carga em um sandbox, cujos limites são menores que os do modo live.

Armadilhas

Reutilizar uma chave de idempotência em requisições realmente diferentes "por segurança": a Stripe trata a divergência de parâmetros como erro, e não deixa passar silenciosamente. Enviar chaves de idempotência em GET/DELETE: a documentação da Stripe observa que isso não tem efeito, pois essas operações já são idempotentes por definição.