Pagination, asynchronous tasks, and idempotency¶
When a list is paginated, a request returns a task ID, or a client times out, continue from the contract of that endpoint rather than guessing a shared Product API behavior.
Keep page numbers, offsets, tokens, or cursors exactly as the endpoint documents. Treat tokens and cursors as opaque values.
For an asynchronous operation, save the returned task, run, execution, statement, or resource ID; query current state; then read and validate its result or artifacts.
Set a deadline, maximum attempt count, and bounded wait when polling. Treat unknown states as incomplete rather than successful.
Use an idempotency key only when the endpoint explicitly supports it. Keep it stable for one business operation and use a new key for the next operation.
A network timeout does not prove that the service rejected the request. Query any known result first, then retry only when the endpoint contract and the possible side effects make it safe.