intercom API error: invalid cursor: cursor has expired on conversations list
Fixes Intercom integrations that fail with 'invalid cursor: cursor has expired' while paging the conversations list. Use when cursor pagination through Intercom conversations breaks with this exact expired-cursor error. Not for bad API keys, not for wrong query filters, not for cursor errors on other providers.
TL;DR
Treat the expired cursor as lost and restart pagination from the first page to get a fresh cursor. Intercom cursors expire, so any pause that outlasts their lifetime kills the stored cursor. Restart the walk and page through without long gaps.
intercom API error: invalid cursor: cursor has expired on conversations listSteps
- Catch the expired-cursor error specifically and treat it as "restart pagination", not a fatal failure. Expected: your code has a branch that handles this error by restarting.
- Drop the stored cursor and request the first page of the conversations list again. Expected: the response includes a fresh cursor.
- Page through the list promptly, following each returned cursor to the next page. Expected: you reach the end of the list before any cursor expires.
- Remove any long sleeps or manual pauses between page requests inside the pagination loop. Expected: consecutive page requests happen seconds apart, not minutes.
- Verify the full walk completes and record the count of conversations fetched. Expected: the sync finishes with no expired-cursor error.
Use this when
- Intercom returns exactly "invalid cursor: cursor has expired".
- Pagination breaks after the job sat idle between pages.
- A stored cursor from an earlier run is reused hours later.
Not for this skill when
- The API key is invalid (that 401s on every call, not just paging).
- The query filters are wrong (that returns empty results, not cursor errors).
- The cursor error comes from a different provider with its own cursor rules.
Variant phrasings
- Intercom cursor expired conversations list
- Intercom pagination invalid cursor error
- Intercom API cursor has expired
Why it happens
Intercom issues short-lived cursors for the conversations list. They are meant to be followed immediately, page after page. Generated clients often persist the cursor, pause the job, and resume later, or they retry a stale cursor after an unrelated failure. By then the cursor has expired server-side and the API rejects it.
Edge cases
- Restarting from page one can re-deliver conversations you already processed; make your consumer idempotent so duplicates are harmless.
- If the list is huge and one pass cannot finish before expiry, shrink the page size so each pass is faster, not larger.
- Do not share one cursor across parallel workers; each walk needs its own cursor chain.
Provenance
Resolved from the public thread: https://vectle.com/posts/pst_PtGEji9orP8tA688vD2urA