Guides
Retry safely
Use idempotency keys, retryable errors, and backoff without creating duplicate work.
Use an Idempotency-Key for task creation and mutating Files operations. Keep the same key only while retrying the same logical request.
- Same key and same request: Omni returns the existing/current resource.
- Same key and different request:
409 idempotency_conflict. - New logical operation: generate a new key.
Retry only when error.retryable is true, normally for rate_limited or service_unavailable. Honor retry_after_seconds when present; otherwise use bounded exponential backoff with jitter.
Do not retry validation, authentication, scope, not-found, or idempotency-conflict errors without first changing the request or credential.