---
title: idempotency_conflict — Idempotency key reused
description: "HTTP 409 idempotency_conflict: The Idempotency-Key has already been used with a different request payload."
canonical_url: "https://cascades.crscreditapi.com/docs/api/errors/idempotency_conflict"
doc_version: "1.0.0"
last_updated: "2026-10-09T18:04:24Z"
http_status: 409
source: config/api_error_codes.yml
---

# `idempotency_conflict` — Idempotency key reused

**HTTP 409 Conflict**

Message: "The Idempotency-Key has already been used with a different request payload."

Envelope schema: `ErrorEnvelope` in [openapi.json](https://cascades.crscreditapi.com/openapi.json#/components/schemas/ErrorEnvelope) ([YAML](https://cascades.crscreditapi.com/openapi.yaml)).

## What causes it
- The same `Idempotency-Key` was sent by this API client with a different `payload`, `execution_mode`, or `external_reference` (trigger), or a different row set (batch). Keys are compared per client, so two clients may reuse a value.
- A key was recycled after the client-side request object changed — for example a retry that regenerated a timestamp inside the payload.

## How to fix it
1. Generate a new key (a UUID) for every distinct request; reuse a key only to retry the byte-identical request, which returns the original execution or batch.
2. Store the key alongside the request in your own system before sending, so a crash between send and response can be replayed safely.

## Operations that return it
- [POST /workflows/{id}/trigger](/docs/api/workflows/trigger-workflow) — Trigger a workflow
- [POST /workflows/{id}/batches](/docs/api/batches/create-batch) — Create a batch from N rows

## Example response

```http
HTTP/1.1 409 Conflict
Content-Type: application/json
```

```json
{
  "error": {
    "code": "idempotency_conflict",
    "message": "The Idempotency-Key has already been used with a different request payload.",
    "details": [],
    "request_id": "6f1c2a3e-8d4b-4c5e-9f0a-1b2c3d4e5f60",
    "doc_url": "https://cascades.crscreditapi.com/docs/api/errors/idempotency_conflict"
  }
}
```

## Related
- [/docs/concepts/idempotency](/docs/concepts/idempotency)

[All error codes](https://cascades.crscreditapi.com/docs/api/errors.md)

## Sitemap

See the full [sitemap](https://cascades.crscreditapi.com/sitemap.md) for all pages.