Saltar al contenido principal

Idempotencia

Toda tool de escritura acepta un argumento opcional idempotency_key. Se envía al endpoint como la cabecera X-Idempotency-Key que la API REST ya honra — ve Idempotencia en la API.

{ "name": "dunning_charges_create",
  "arguments": {
    "person_id": "…",
    "original_amount": 1500.0,
    "issue_date": "2026-07-10",
    "due_date": "2026-08-10",
    "idempotency_key": "7c4a8d09-ca37-4f21-b1f0-3d2f2b8c9a11"
  } }
FormatoCadena opaca, de 1 a 255 caracteres. Un UUID es la elección habitual.
Repetición con el mismo cuerpoDevuelve la respuesta grabada, sin ejecutar la operación de nuevo.
Repetición con cuerpo distintoConflicto — el error de la API vuelve como resultado isError.

El argumento no forma parte del cuerpo: la tool lo separa y lo envía solo como cabecera. Las tools de lectura no lo ofrecen.

Por qué un agente necesita esto más que tu backend​

Un cliente MCP que agota el tiempo y reintenta, o un modelo que decide "no estoy seguro de que eso funcionó, lo rehago", es exactamente el patrón que crea el segundo cobro, el segundo acuerdo o el segundo deudor. Tu backend tiene un bucle de reintento que escribiste tú; el agente tiene un juicio.

Envía una clave siempre que la operación cree algo o hable con alguien.

:::warning Las que salen al mundo Las tools que notifican a un deudor (dunning_charges_notify, dunning_notifications_create, dunning_notifications_resend) o prueban y reintentan un webhook llevan idempotentHint: false: repetirlas vuelve a enviar. Crear un cobro, un acuerdo o una negativación dos veces deja un duplicado que alguien tendrá que deshacer — y, en lo que habla con el deudor, un mensaje que ya salió. Envía idempotency_key en esas incluso cuando creas que no vas a repetir. :::

Idempotencia no es confirmación​

La clave protege contra la repetición de una llamada; la confirmación de tools destructivas protege contra la primera. Son independientes y se combinan: la confirmación decide si la acción debe ocurrir; la clave garantiza que, una vez ocurrida, un reintento no la ejecute dos veces.