Safe mutations and retries

The API treats retries as part of the financial protocol. Inspect each operation's declared headers and body before sending it.

Idempotency keys

When an operation declares Idempotency-Key, supply an opaque value between 8 and 128 characters. Generate one key for one intended mutation and reuse that exact key only when retrying the same content.

Idempotency-Key: expense-create-7b32075e

Reusing a key with different content returns a conflict. A timeout or ambiguous transaction outcome is not permission to create a new key and submit again.

Exact versions

Expense approvals and state-changing actions may require expectedVersion. Read the current resource, send the version you reviewed, and handle 409 by reloading rather than overwriting a newer revision.

Approvals are bound to the exact expense version. A material revision invalidates prior authority.

Durable work

• 201 means a resource was created.
• 202 means durable work was accepted; it does not mean a payment has settled.
• Payment state becomes final only after reconciliation verifies the expected Arc receipt and events.
• Server-Sent Events and polling report state changes but never authorize a mutation.