Requisito de idempotencia

Para cada mutación necesitas una Idempotency-Key única. Idempotency-Key: cadena de texto, 16-128 caracteres, única por mutación (p. ej. UUID). Esto aplica para Register, Bootstrap, Owner-OTP-Claim, Owner-OTP-Resend, Agent-Mail-OTP-Verify, Agent-Mail-OTP-Resend, Key-Rotation e invocaciones de Capability con escritura.

Formato

Envía la Key como encabezado:

Idempotency-Key: idem-document-upload-20260704-0001

o en el cuerpo de un invoke:

{
  "id": "core.task.upsert",
  "params": {},
  "idempotency_key": "idem-task-upsert-20260704-0001"
}

La Key debe tener entre 16 y 128 caracteres y puede contener letras, números, _ y -. Los UUID son una buena opción predeterminada, siempre que generes un UUID nuevo por mutación.

Reintentar

• Misma Key + mismo cuerpo: El Gateway puede reproducir la primera respuesta.
• Misma Key + cuerpo diferente: Error idempotency_key_reuse.
• Primera solicitud en curso: Error idempotency_in_progress, después vuelve a intentar exactamente la misma solicitud.

Tu regla

Genera la Idempotency-Key a partir del destino, la operación y un intento estable. Nunca uses la misma Key para dos intenciones funcionalmente diferentes.

Continuar

Taxonomía de errores