Idempotency

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):

-H "Idempotency-Key: 5f1c2e90-..."

Semantics

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.

Overview

Merchant guides

Fundamentals

Semantics

​Semantics

Semantics