Skip to content

Request IDs, replay and recovery

Implemented

Send a write again safely after a lost response, and never duplicate paid or published work.

Use the ID field declared in each write tool's input schema. Most writes use requestId. Media proposals use input.clientRequestId, and create_project, export_project and prepare_seedance_reference use clientRequestId. The ID is a stable UUID for one exact intent, not a retry counter.

After an uncertain response#

  1. Read the saved state with the matching read tool.
  2. If the result is still uncertain, replay the same ID and identical payload.
  3. If the server reports a conflict, read the current record before making a new decision.

A replay of an already committed write returns the original result. Changed input with the same ID can fail with IDEMPOTENCY_CONFLICT or a domain conflict. A new ID creates a new operation. Never mint a new ID to repair a lost paid generation, provider call, upload, approval, or publication response.

Updated 2026-10-17: content retention can remove creative payloads after a completed, never-started cancellation. Minimal IDs and status remain, but the deleted payload cannot be returned again. Erased Instagram approval/readiness inputs can return IDEMPOTENCY_CONFLICT; their read endpoints return no current payload. This does not authorize a replacement operation. Retention cleanup remains disabled pending its activation checks.

export_project derives one request ID for each size from its clientRequestId. A replay with identical input returns the same jobs. After a later edit of the project, the replay finds them among the 50 newest media jobs of the workspace. create_project takes clientRequestId; a replay returns the saved project. convert_project has no request ID: the same projectId, revisionId, to and frames always give the same new project, so a replay returns it and makes no copy. edit_project has no request ID; it uses expectedRevisionId. After a lost edit_project response, read get_project to see if your revision was saved. The generationRequestId of prepare_seedance_reference is not its own key: it is the input.clientRequestId that you will send to propose_generation.

Read tools can also take a requestId to select a saved request. That is a lookup key, not a new write. The generated reference labels lookup and idempotency keys separately.