API Idempotency

Executive Summary

API Idempotency defines how Algosure APIs should handle retries for state-changing operations. Unsafe commands that may be retried must support idempotency keys.

Why This Exists

Mobile networks, web retries, integration callbacks, payment workflows, and AIOS tool calls can submit the same command more than once. Idempotency prevents duplicate business effects.

Owner

The owner is the Chief Product Officer and Enterprise Architect.

Business Value

Idempotency protects customers from duplicate submissions, duplicate payments, duplicate notifications, duplicate AI tasks, and inconsistent workflow state.

Idempotency Flow

sequenceDiagram
    participant Client as API Consumer
    participant API as API Boundary
    participant Idem as Idempotency Check
    participant App as Application Service
    participant Domain as Owning Domain

    Client->>API: Submit command with idempotency key
    API->>Idem: Check key in tenant and operation scope
    Idem-->>API: New request
    API->>App: Execute command
    App->>Domain: Apply business behavior
    Domain-->>App: Return result
    App-->>API: Store result for key
    API-->>Client: Return result

Idempotency Rules

Rule	Requirement
Required for retryable commands	Commands that create external effects, payments, submissions, notifications, AI tasks, or workflow transitions require idempotency keys.
Scoped by tenant and operation	Idempotency keys must be evaluated within tenant, organization where applicable, actor, and operation context.
Same key means same intent	Reusing a key with different command content is an idempotency conflict.
Replays return prior result	A duplicate valid request should return the prior accepted result where safe.
Failures are classified	Retry behavior depends on whether the prior failure was transient, validation, authorization, or conflict.
Idempotency is auditable	Accepted, replayed, and conflicting idempotency decisions must be traceable.

Idempotency Use Cases

Use Case	Why It Needs Idempotency
Bid submission actions	Prevent duplicate submission or approval side effects.
Payment commands	Prevent duplicate charges or payment state transitions.
Notification sends	Prevent duplicate customer messages.
Integration callbacks	Handle repeated external delivery attempts.
AIOS tool calls	Prevent duplicate AI tasks or repeated state-changing outputs.
Document generation	Prevent duplicate document packages or conflicting workflow artifacts.

Non-Implementation Boundary

This document does not define key format, storage schema, retention duration, exact conflict response, or endpoint-specific idempotency requirements.