API design pattern
API pagination: offset vs cursor under changing data
Choose offset, page, keyset, or cursor pagination based on data churn, stable ordering, random access, caching, and client recovery requirements.
Offset pagination is simple and supports random access, but inserts and deletes can shift rows between requests. Cursor or keyset pagination follows a stable ordering boundary and scales better for changing datasets, but requires opaque state and careful tie-breakers.
Treat the complete response as an evidence record: status, headers, provider code, request identifier, method, and raw body. The sequence below separates what the response proves from the checks still needed before a safe retry or code change.
Diagnostic procedure
Work from evidence to recovery.
- 01
Define a total order
Use a stable sort with a unique tie-breaker, such as created_at plus id, before encoding a cursor.
- 02
Keep cursors opaque
Clients should pass the cursor back unchanged; the server owns its format, version, and validation.
- 03
Design recovery
Document expiry, invalid cursors, direction, page-size changes, and how clients resume after a partial sync.
page=2&limit=100 while new rows are inserted → duplicates and gaps
after=opaque(created_at,id)&limit=100 → resume after stable boundary
Evidence
HTTP 429: A rate, quota, concurrency, or resource lock limit blocked the request.
Retry-After is present; it should take precedence over a guessed delay.
The reported request window has no remaining capacity.
Next checks
01Parse Retry-After as either delta-seconds or an HTTP date before scheduling the next attempt.
No account · no upload · no endpoint calledOpen the full incident decoder and operating notes →
FAQ
Before you ship
Does APITC send this evidence to an API?
No. The matching and calculations in the linked workbench run in the active browser tab.
Should every pagination response be retried?
No. Retry behavior depends on the method, idempotency protection, provider instructions, and whether the failure is temporary.
Protocol behavior checked against the GitHub REST API pagination. Recheck your pinned provider/API version before production deployment.