Networks fail; agents retry. To make retries safe, every non-GET request must send an
Idempotency-Key header — a unique value per logical action (a UUID works well):
For 24 hours, the Gateway remembers each (key, request body) pair and the response it produced:
Same key + same body → the original response is replayed; the action runs once.
Same key + different body → 409 IDEMPOTENCY_CONFLICT (you reused a key for a different action).
Key in flight → 409 while the first request is still processing.
# First call performs the work:curl -X POST .../agent/v1/products \ -H "X-Agent-Key: sq_agt_xxx" -H "Idempotency-Key: abc-123" \ -d '{"title":"Serum","price":29.99}'# Identical retry returns the SAME result — no duplicate product:curl -X POST .../agent/v1/products \ -H "X-Agent-Key: sq_agt_xxx" -H "Idempotency-Key: abc-123" \ -d '{"title":"Serum","price":29.99}'
Generate a fresh key for each distinct action. Reusing one key across different payloads is a
conflict by design — it’s the guardrail that prevents double-sends and double-charges.
