Skip to main content
Every mutating endpoint on Stella accepts an Idempotency-Key header. Replays of the same key within 24 hours return the cached response from the first call — same status code, same body, byte for byte. This makes flaky-network retries safe (you’ll never double-charge a customer) and is essential for AI agents whose tool-use loops often include retry-on-error logic.

​
How to use it

Generate a UUID per logical operation. Attach it to every mutation that’s part of that operation. Retries reuse the same key.

​
Lifetime

Cached responses live 24 hours, then a daily cleanup task deletes them. After that window, the same key is treated as a fresh request.

​
Where it’s required

  • All POST, PATCH, DELETE on /api/storefront/cart/*, /api/storefront/customer/*, /api/agent/*.
  • Webhook delivery retries (Stella adds the key automatically — your receiver just needs to be idempotent).

​
Where it’s optional

  • GET requests (idempotent by definition).
  • /api/dashboard/* (merchant-trusted).
  • /api/sync/* (Zunkiree integration).
If you omit the header on an endpoint that requires it, you’ll get 400 Bad Request with error: "idempotency_key_required".

​
Conflict handling

If you reuse a key with a different request body (different endpoint, different params), Stella returns:
This is a defensive guard — it should never fire in normal use, since you’d be reusing keys across different operations.