# Idempotency retries and cancellation

Availability: **Proposed specification**  
Documentation: **1.1** | Updated: **19 September 2026**

[Documentation home](../README.md)

## Submission idempotency

IDEM-01 Scope the idempotency key by authenticated tenant and operation. Persist the key, request fingerprint and task identifier atomically. Repeating the same key and fingerprint returns the original task. Reusing the key with different content returns a conflict and leaves the original contract unchanged.

The key retention period must cover the supported request-retry, task and reconciliation windows. Before retrying after a transport timeout, a client should query the task or repeat the original request with the same key. A new key can create a new task.

## Retry eligibility

| Failure class | Required handling |
| --- | --- |
| Temporary transport or runtime failure | Retry only a declared safe workload within attempt, deadline and budget limits. |
| Invalid input or denied permission | Do not automatically retry unchanged input. |
| Unknown external side effect | Query or reconcile the external system before repeating an action. |
| Superseded executor returns | Retain late evidence; reject state changes from an old generation. |
| Delivery acknowledgment lost | Return the recorded delivery; do not create another acceptance or charge. |

RETRY-01 A new attempt MUST have a new identifier and lease generation. The old attempt remains visible. Resource consumption on a stale node can continue during a partition, but its output cannot replace the current authorized result.

## Cancellation races

CANCEL-01 Acknowledging a cancellation request means it has been recorded, not that execution has stopped. The coordinator orders cancellation confirmation against delivery using atomic state transitions. If delivery wins, the cancellation response must expose that state and apply the frozen acceptance and fee policy.

For a confirmed cancellation, retire execution authority and retain any incurred usage. A device gateway must distinguish command acknowledgment from observed physical completion. Emergency stops and safety interlocks remain the responsibility of the local control system.

Cross-system exactly-once execution is not a guarantee of this design. External actions require their own idempotency, reconciliation and compensation rules.

[Previous](./acceptance-lifecycle.md) | [Next](./api-design.md)