Error: idempotency_conflict

Qué significa

Enviaste dos requests con la misma Idempotency-Key pero con cuerpos diferentes. Emitia detectó que no es un reintento del mismo request, sino dos operaciones distintas intentando usar la misma clave.

Envelope de ejemplo

{
  "error": {
    "type": "idempotency_error",
    "code": "idempotency_conflict",
    "message": "Esta Idempotency-Key ya fue usada con un body diferente. Usa una clave nueva para este request.",
    "doc_url": "https://docs.emitia.co/errors/idempotency_conflict",
    "request_id": "req_01HX…"
  }
}

HTTP status: 409 Conflict

Causas frecuentes

Causa	Descripción
Reutilizar la misma clave para facturas diferentes	La clave debe ser única por operación lógica
Incrementar el precio y reintentar con la misma clave	El body cambió → es una operación diferente
Código de retry que genera una clave nueva en cada intento	La clave debe generarse UNA VEZ antes del bucle de retry

Cómo resolverlo

La regla es simple: una clave por operación lógica. Si quieres crear una factura diferente, genera una clave nueva.

// CORRECTO: genera la clave ANTES del bucle de retry
const idempotencyKey = randomUUID(); // Una sola vez

for (let attempt = 0; attempt < 3; attempt++) {
  const res = await fetch('/v1/invoices', {
    method: 'POST',
    headers: { 'Idempotency-Key': idempotencyKey }, // Misma clave
    body: JSON.stringify(invoice),
  });
  if (res.ok) break;
}

// INCORRECTO: genera una clave nueva en cada reintento
for (let attempt = 0; attempt < 3; attempt++) {
  const res = await fetch('/v1/invoices', {
    method: 'POST',
    headers: { 'Idempotency-Key': randomUUID() }, // DISTINTA en cada intento ← MAL
    body: JSON.stringify(invoice),
  });
}

Diferencia entre 409 por idempotencia y 409 por conflicto de negocio

code	Causa	Acción
idempotency_conflict	Misma clave, body diferente	Genera una clave nueva
conflict	Otro conflicto de negocio (ej: numeración duplicada)	Revisa la lógica de negocio

Ver también

• Conceptos: Idempotencia — patrón completo de retry seguro