Handle retries, limits, and partial results
Recover from failures while keeping job creation predictable and your work bounded.
1. Keep the original request identity
Generate one idempotency key per intended mutation and preserve it with the input. On a timeout, retry only the same unchanged request with that key. For MCP, use the stable client_request_id.
2. Respect retry guidance
For retryable rate or concurrency limits, honor Retry-After and use bounded backoff. Stop at your task deadline. Authentication, scope, quota, and unavailable-capability errors require corrective action rather than repeated requests.
3. Inspect the existing job
A job_not_ready response means you should check the original job, not create another. Distinguish a successful job from partial, failed, or canceled outcomes.
4. Report what was returned
Read is_complete and next_cursor when paging through results. A continuation cursor is not a source-page number. If work ends early, report the incomplete coverage and keep the request and job IDs for troubleshooting.