> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sherlocker.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# idempotency_conflict

> Erro 409: conflito de Idempotency-Key (em andamento ou body diferente)

**Status HTTP:** `409`

## O que significa

A `Idempotency-Key` enviada conflita com uma requisição anterior. Há dois cenários:

1. **Requisição concorrente**: outra requisição com a mesma key ainda está em andamento. A primeira vence; a concorrente recebe `409` enquanto a original não termina.
2. **Mesma key, conteúdo diferente**: uma requisição anterior já usou essa key com um conteúdo diferente dentro da janela de deduplicação de 24 horas.

O que conta como "mesmo conteúdo" depende do motor:

* **`POST /analyses`**: o body da requisição.
* **`POST /operations`**: o payload multipart — o conteúdo dos arquivos (`file` e `xmls`) e os campos (`cedente_cnpj`, `engine_id`, `purpose`, `legal_basis`). Trocar o arquivo, o ZIP ou qualquer campo com a mesma key gera conflito.

Para referência: mesma key + **mesmo** conteúdo dentro de 24 horas não é erro, retorna `200` com o body original da `202`, sem nova cobrança.

<Note>
  No `POST /operations` (Motor de Borderô), o header `Idempotency-Key` é **opcional**: este erro só pode ocorrer quando você envia a key. Sem ela, cada POST cria uma operação nova — sem deduplicação e sem conflito. No `POST /analyses`, a key continua obrigatória.
</Note>

## Causas comuns

* Retries automáticos disparando em paralelo com a requisição original ainda em voo.
* Reuso da mesma key após corrigir um erro de validação (o conteúdo mudou, a key não).
* Key gerada de forma não única no seu sistema (por exemplo, key fixa por cliente em vez de por job/borderô).

## Como corrigir

* **Concorrência**: não reenvie o POST. Aguarde a requisição original terminar e consulte via `GET` (`/analyses/{id}` ou `/operations/{id}`) usando o `id` da resposta `202` original.
* **Conteúdo diferente**: se a mudança é intencional (nova análise, outro borderô), gere uma **nova** `Idempotency-Key`.
* **Retry seguro**: em timeout ou erro 5xx de rede, reenvie com a **mesma** key (nunca gere key nova em retry, há risco de cobrança dupla). Em 4xx de validação, corrija e use key **nova**.
* Gere a key como UUID e amarre ao ID interno do job (ou do borderô) no seu sistema, garantindo uma key por requisição pretendida.

## Exemplo

```json theme={null}
{
  "type": "https://docs.sherlocker.com.br/problems/idempotency_conflict",
  "title": "Conflict",
  "status": 409,
  "code": "idempotency_conflict",
  "detail": "A request with this Idempotency-Key is already in progress.",
  "instance": "/v1?request_id=req-uuid-here"
}
```

O texto de `detail` varia conforme o cenário.

## Relacionado

* [Erros da API](/motor-analise/erros)
* [Idempotência](/motores/idempotencia)