Idempotency-Key header. Each operation is either safe to repeat by design, or gives you a way to check what happened before you repeat it.
What to do after a failure
See Errors for what each status means and Rate limits for how long to wait after a
429.
Bulk API
Uploads are built to be run again, on a schedule or after a failure.
If
/start times out, read the job with GET /bulk/jobs/{job_id} before sending the file again. See the Conversations guide for how to keep conversation_id and event_id stable across uploads.
MCP tools
Every tool states whether it is safe to repeat in its MCP annotations, which your client receives in the tool list:readOnlyHint: truemeans the tool changes nothing.idempotentHint: truemeans calling it again with the same arguments has no further effect.
Jobs
Tools that start long-running work return a job id right away. Reading a job’s status is always safe, and a failed status read does not cancel or restart the job. Read the status again with the same id; do not start the job again.Check before repeating a write
When a write times out or returns5xx, it may already have taken effect. Look for what the call would have made before calling it again:
- After
create_worksheet, calllist_worksheets. - After
enrich_worksheet, calldescribe_tableon the worksheet and look for the new columns.
Request ids
agent_search, in workspaces where it is turned on, takes a requestId. Give each search its own id and reuse that id when you retry: the same requestId with the same arguments returns the original search instead of running, and billing, a second one.
Rippit CLI
With--format json, a failed command reports retryable in its error. When it is false, check the result before running the command again. For example, a worksheet creation that timed out reports creation_unconfirmed; list worksheets with rippit data list --kind worksheet before creating it again. See Rippit CLI.