Be idempotent and predictable where it matters

The same call should produce the same result, and retries must be safe, so agents can recover without causing duplicate side effects.

Why

Agents retry. Unlike humans who notice a double-charge and call support, agents will silently retry a failed write and create a duplicate record or trigger a duplicate transaction. Speakeasy identifies Predictability as a foundational AX property. Stripe's idempotency key pattern is the industry standard: the client generates a unique key per intent, and the server returns the same result for any subsequent call with that key. This is especially critical in fintech and e-commerce where non-idempotent retries directly cause financial harm.

Do

Use idempotency keys on writes.

Don't

Create a new resource on every identical retry.

Artifact

Send an Idempotency-Key on writes so the same key returns the same result (safe retries). See the refund example in AX-SYS-13.