Skip to content

Idempotency Standard

Purpose

The Idempotency Standard defines how future API contracts protect unsafe commands from duplicate effects.

Required For

Command Type Reason
Payment and billing commands Prevent duplicate charges or state transitions.
Bid submission and approval commands Prevent duplicate workflow effects.
Notification send commands Prevent duplicate messages.
Integration callbacks Handle repeated external callbacks.
AIOS execution requests Prevent repeated tool actions.
Document or package generation Prevent duplicate artefacts and conflicting records.

Key Rules

  • Unsafe retryable commands require Idempotency-Key.
  • Keys are scoped by tenant, organization where applicable, actor, API operation, and command intent.
  • Reusing the same key with the same intent returns the prior accepted result where safe.
  • Reusing the same key with different request content returns IDEMPOTENCY_CONFLICT.
  • Missing key on required operations returns IDEMPOTENCY_KEY_REQUIRED.
  • Idempotency decisions must be auditable.

Flow

sequenceDiagram
    participant Client
    participant API
    participant Idempotency
    participant Service as Application Service

    Client->>API: Unsafe command with Idempotency-Key
    API->>Idempotency: Check key and request fingerprint
    alt New key
        API->>Service: Execute command
        Service-->>API: Result
        API->>Idempotency: Store result
    else Existing same intent
        Idempotency-->>API: Prior result
    else Existing different intent
        Idempotency-->>API: Conflict
    end

Specification Requirement

Every future endpoint spec for an unsafe command must declare whether idempotency is required, optional, or not applicable.