Skip to content
Emitia

Error: missing_idempotency_key

Qué significa

Section titled “Qué significa”

Enviaste un POST a un endpoint cobrable sin incluir el header Idempotency-Key. Este header es obligatorio en todas las operaciones que crean o modifican recursos cobrables (facturas, notas, clientes).

Envelope de ejemplo

Section titled “Envelope de ejemplo”
{
  "error": {
    "type": "validation_error",
    "code": "missing_idempotency_key",
    "message": "El header 'Idempotency-Key' es obligatorio para este endpoint.",
    "doc_url": "https://docs.emitia.co/errors/missing_idempotency_key",
    "request_id": "req_01HX…"
  }
}

HTTP status: 422 Unprocessable Entity

Por qué es obligatorio

Section titled “Por qué es obligatorio”

Sin idempotencia, un timeout o error de red puede crear facturas duplicadas. El header obligatorio fuerza a los integradores a pensar en el retry pattern desde el principio, no como una mejora posterior.

Cómo resolverlo

Section titled “Cómo resolverlo”

Agrega el header con un UUID v4 generado antes de cada operación:

Terminal window
curl -X POST https://api.emitia.co/v1/invoices \
  -H "Authorization: Bearer sk_test_…" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{...}'
import { randomUUID } from 'crypto';


const res = await fetch('https://api.emitia.co/v1/invoices', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer sk_test_…',
    'Idempotency-Key': randomUUID(), // Genera ANTES del bucle de retry
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ ... }),
});

Ver también

Section titled “Ver también”