Idempotency

Idempotency-Key is optional. Use it when your system may resend the same logical operation because of a timeout or network retry.

• The same key and same payload return the original operation instead of executing and charging twice.
• The same key with a different payload returns HTTP 409.
• A key stays bound once execution may have contacted a provider, including when that operation failed. Replaying returns the recorded outcome. This is the point of an idempotency key: after a timeout you cannot know whether the work happened, so the key protects you from paying for it twice. To deliberately retry a failed operation, use a new key.
• The sole persisted exception is NO_ELIGIBLE_ROUTE, which proves no provider call started. Its key is released and can be reused. Admission limits reject before an operation is created.
• Different keys are different billable operations, even when their URLs are identical.
• Requests without a key are always treated as new operations.
• A key outlives the result it replays. Once the retention window has passed, replaying returns HTTP 410 with RESULT_EXPIRED rather than the body.

Every operation also receives a unique X-Request-Id; this is generated by Struqter and is not a substitute for a client-supplied idempotency key.