invalid next token error when using Nomad /v1/jobs pagination

Recommended approach

Treat any HTTP 400 response from the /v1/jobs endpoint as a pagination‑related client error and do not depend on the exact text invalid next token. The Nomad documentation explicitly states that this message may change between releases, so client code should base its decision on the status code alone.

Confirmed facts

• The Nomad /v1/jobs API returns an opaque next_token for pagination.
• If the token supplied in a subsequent request does not exactly match the value returned by the previous call (including any required URL‑encoding), the server responds with HTTP 400 and a JSON payload that currently contains the string invalid next token.
• The documentation warns that the exact error string is not stable across versions.

Likely explanation

Because the error message is not guaranteed to stay the same, distinguishing token‑related failures from other 400 cases (e.g., an invalid limit or malformed filter) by inspecting the response body is unreliable. All pagination‑specific problems manifest as 400 responses, so the safest, version‑agnostic strategy is to handle them uniformly.

Steps for robust client handling

1. Make the paginated request with the desired query parameters (filter, prefix, suffix, limit) and include the next_token received from the previous page.
2. Check the HTTP status code of the response.
3. If the status is 400, treat the request as a pagination/client error:
• Log the full response body for debugging (this helps you see whether the issue is the token or another parameter).
• Either restart pagination with the same parameters (if you suspect the token expired) or inform the user of a bad request.
4. If the status is 200, process the job list and extract the new next_token for the next page.

When additional detail might change the recommendation

If Nomad ever adds a stable error‑code field (e.g., "error_code": "invalid_next_token") to the 400 payload, you could inspect that field for finer‑grained handling. Until such a field is documented and confirmed stable, rely on the status code alone.