Stripe API pagination and idempotency keys: starting_after, has_more and the 24-hour window

What it is

Stripe's pagination reference describes list methods that "share a common structure and accept, at a minimum... limit, starting_after, and ending_before," using "cursor-based pagination... Both parameters accept an existing object ID value... and return objects in reverse chronological order," and states the two cursor parameters "are mutually exclusive." Every list response wraps results as {"object": "list", "data": [...], "has_more": bool, "url": "..."}, with limit defaulting to 10 and capped at 100; Stripe's client libraries additionally offer "auto-pagination helpers to traverse all pages of a list" so callers rarely walk starting_after by hand. For writes, Stripe's idempotency reference explains that an Idempotency-Key header lets a client "safely repeat the request without risk of creating a second object or performing the update twice," because Stripe "sav[es] the resulting status code and body of the first request... regardless of whether it succeeds or fails," saved keys may be pruned once they are at least 24 hours old (a reused key is then treated as a new request), and a replayed response carries Idempotent-Replayed: true. Reusing a key with different parameters is rejected: "the idempotency layer compares incoming parameters to those of the original request and errors if they're not the same." Results are saved only once an endpoint starts executing, so a request that failed validation or collided with a concurrent request can be retried with the same key. Stripe's rate-limits page lists a global limit of 100 requests per second in live mode and 25 in a sandbox, 25 per second per endpoint unless noted, and 20 read requests per second for the Search API; limited requests get 429 plus a Stripe-Rate-Limited-Reason header (global-rate, endpoint-rate, global-concurrency, endpoint-concurrency or resource-specific). A 429 without that header is not a rate limit — it may be a lock_timeout on an object another request holds.

Why it matters

Offset-style paging is not offered at all on Stripe's v1 list endpoints, so any client-side attempt to compute a page number will not work; idempotency keys are the documented way to make a retried POST (after a timeout or a dropped connection) safe from creating a duplicate charge or customer.

How to apply

• Read has_more, not the returned count, to decide whether to fetch another page; pass the last item's id as starting_after.
• Prefer the client library's built-in auto-pagination iterator over hand-rolled loops.
• Generate a fresh idempotency key (Stripe suggests a v4 UUID) per logical write attempt, and reuse the same key only when retrying the exact same request after a network failure.
• Keep idempotency keys free of sensitive data and at most 255 characters, per Stripe's constraints.
• On 429, back off exponentially with jitter and read Stripe-Rate-Limited-Reason; never raise concurrency to compensate. Do not load-test against a sandbox, whose limits are lower than live mode.

Pitfalls

Reusing an idempotency key across genuinely different requests "to be safe" — Stripe treats a parameter mismatch as an error, not a silent pass-through. Sending idempotency keys on GET/DELETE, which Stripe's docs note has no effect since those are idempotent by definition.