GraphQL cursor expiration returns GRAPHQL_PARSE_FAILED with "Invalid cursor" after 15-minute inactivity

Answer

The cursor TTL enforced by the Jira Align GraphQL gateway is approximately 15 minutes of inactivity. This value is not exposed in the API schema, is not documented as configurable per tenant, and there is no provided method to refresh or extend a cursor without re‑querying the first page. When a cursor has expired, the gateway returns a GRAPHQL_PARSE_FAILED error with the message "Invalid cursor", which is indistinguishable from the error produced by a malformed cursor unless the gateway includes a custom error code in the extensions field.

Confirmed facts

• The connection payload does not contain a cursorExpiresAt or similar field.
• No API operation such as refreshCursor or pagination‑TTL argument exists in the schema.
• Sorting via orderBy must be stable; changing the sort order invalidates any existing cursor immediately, independent of the TTL.

Likely explanation

Based on user reports and typical Relay cursor implementations, the gateway likely stores cursor state in a short‑lived server‑side cache (or signed token) that is cleared after ~15 minutes of no use. Because this cache is internal, the TTL is not surfaced to clients and can vary between deployments or tenants.

Steps to verify behavior

1. Capture the full error response (including extensions) when using a cursor that has been idle for >15 minutes.
2. Produce a deliberately malformed cursor (e.g., a random base64 string) and capture its error response.
3. Compare the two responses: if the extensions object contains a distinct code (e.g., CURSOR_EXPIRED) only for the expired case, you can differentiate them; otherwise treat both as the same failure.
4. If the extensions lack a distinguishing code, implement a retry strategy that treats any GRAPHQL_PARSE_FAILED with "Invalid cursor" as a potential expiration and, after a short back‑off, refetches the first page to obtain a fresh cursor.

Missing diagnostic detail

To decide whether a custom error code is present, please check whether the extensions field of the expired‑cursor error contains a code such as CURSOR_EXPIRED or any other identifier that differs from the malformed‑cursor case. This detail changes the recommendation: if a unique code exists, you can rely on it for expiration detection; otherwise you must assume indistinguishability.