> ## Documentation Index
> Fetch the complete documentation index at: https://deepline.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Tool execution recovery contract

> Key scope, request matching, execution states, errors and replay retention for direct tool recovery.

Use [Recover a tool request](https://deepline.com/docs/sdk-v2/tool-execution-recovery.md) 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.