Skip to main content

​
What it means

Aeris remembers every idempotency_key it accepts on a mutating tool along with a hash of the payload. If the same key comes back with a different payload, that’s a client bug — either a stale key was reused across intents, or two different intents accidentally share a key. This is not retryable with the same key. The client must mint a fresh key.

​
How to fix

  • Generate a new idempotency_key (UUIDv4 recommended) for the new intent.
  • Audit how your client scopes keys — keys should be per-intent, not per-session or per-user.
  • If you meant to replay the original call, use the original payload with the original key.

​
Response envelope

{
  "ok": false,
  "error_envelope": {
    "code": "IDEMPOTENCY_CONFLICT",
    "message": "The idempotency_key was previously used with a different payload.",
    "docs_url": "https://tryaeris.ai/docs/mcp/errors/idempotency-conflict",
    "retryable": false,
    "retry_after_ms": null,
    "details": {
      "idempotency_key": "c3f3f0be-4b7a-4e7e-9e5e-8f5a1a7d1b12"
    }
  }
}