Tool execution recovery contract

Use Recover a tool request for the SDK, CLI and HTTP procedure. These rules apply to direct tool executions; Play workflows recover through their saved run IDs.

Key and input rules

Rule	Behavior
Key length	1–200 ASCII characters.
Allowed characters	Letters, digits, `.`, `_`, `:`, and `-`.
Equality	Case-sensitive. Whitespace is rejected, never trimmed.
Scope	Keys are unique within a workspace and bound to the original caller authorization identity. A key is not a credential.
Same key, same request	Observe, resume, or replay the original execution.
Same key, different request	`409 IDEMPOTENCY_INPUT_MISMATCH`. no new provider call.
New key, same request	A separate execution that may be charged again.

The server hashes the canonical request with SHA-256. Object property order does not create a conflict. array order and values do. The fingerprint includes the tool and execution-affecting options. Keep the original payload when retrying, including wait behavior and metadata. Resume through the same SDK, CLI, or HTTP call shape. Response format and metadata headers also participate in comparison, so switching between the high-level SDK’s dataset response and the raw HTTP response can conflict. Key lookup can inspect the saved response without resubmitting those options. Use the original API key or caller identity for recovery. Another caller in the same workspace cannot read the execution. attempting to submit the same key from that caller conflicts. Rotating an API key does not transfer its saved executions to the new key. The key stays short even for a large batch. Send the normal payload once per HTTP attempt. The server computes its digest. A digest cannot reconstruct your input, and idempotency does not increase HTTP or provider batch limits. --input @file reads local JSON. It does not enable an unsupported provider file-upload action.

States and errors

State or code	Meaning	Caller action
`running`	The original execution is active or has a recoverable provider job.	Keep the same key. inspect or resume.
`EXECUTION_IN_PROGRESS` (409)	Execution or delivery is still in progress, including a temporary read failure.	Wait or resume later with the same key.
`EXECUTION_RECOVERY_UNAVAILABLE` (503)	The recovery record or saved response cannot be read temporarily.	Retry lookup with the same key. This does not authorize new work.
`EXECUTION_RECOVERY_TIMEOUT` (SDK/CLI)	The caller’s recovery wait budget ended.	Inspect or resume later with the same key. The provider job is not cancelled.
`completed`	The original response was durably saved.	Consume the returned response, including its billing fields.
`EXECUTION_NOT_FOUND` (404)	This workspace has no execution for the key.	Submit the original request with this key.
`IDEMPOTENCY_KEY_INVALID` (400)	The key violates the rules above.	Correct it before submitting work.
`IDEMPOTENCY_INPUT_MISMATCH` (409)	The key is already bound to different input.	Recover the original request. Use a new key only for intentional new work.
`IDEMPOTENCY_KEY_EXPIRED` (410)	The original result’s replay window ended.	Retrieve results from your own durable storage. Do not treat expiry as permission to retry paid work.
`EXECUTION_OUTCOME_UNKNOWN` (409)	Dispatch may have reached the provider, but Deepline cannot safely recover its outcome.	Retain the key and investigate. automatic relaunch is refused.
`IDEMPOTENCY_NOT_SUPPORTED` (422)	The server or requested execution mode cannot provide this recovery contract.	Follow the error’s supported alternative before submitting work.

Completed responses are replayable for 24 hours after completion. The key’s record remains after replay expiry, so reusing an expired key produces an explicit error. Active and ambiguous executions never age into permission to launch another call. Save results in your own durable store if you need them beyond the replay window. An idempotency key cannot guarantee an external provider’s outcome when the provider accepts work and the process dies before its job ID can be saved. Deepline preserves that uncertainty and refuses duplicate dispatch. Once a recoverable async job ID is durably saved, recovery follows that job.

Dispatch support

Recovery is opt-in. Existing calls without a key keep their current behavior. The SDK dispatches keyed work through the recovery-specific POST endpoint, which enforces recovery support and compares the submitted input before provider dispatch. Older servers use a read-only capability check before the legacy execute POST.

​Key and input rules

​States and errors

​Dispatch support

Key and input rules

States and errors

Dispatch support