Idempotencia

Cómo funciona

Elige una clave única por operación (un UUID, o un id propio como un número de pedido) y envíala como Idempotency-Key. Durante 24 horas, la misma clave en la misma ruta devuelve de nuevo el primer resultado, con Idempotent-Replayed: true, en lugar de repetir el trabajo.

• La misma clave con un cuerpo distinto responde 422 idempotency_conflict.
• La misma clave mientras la primera solicitud sigue en curso responde 409 conflict: espera y reintenta.
• Una solicitud que falló no se guarda, así que reintentarla con la misma clave hace el trabajo.
• Las claves se limitan al espacio de trabajo, a quien llama, a la ruta y a su path. Quien llama es la clave de API (o, en la app, el miembro con sesión iniciada): dos claves de API que envían la misma Idempotency-Key nunca se repiten las respuestas entre sí, y una clave de API renovada es un nuevo llamante. La misma clave en las rutas de dos códigos distintos tampoco colisiona.
• PATCH y DELETE no llevan clave: repetirlos deja el mismo estado.

Las repeticiones nunca llevan un secreto

La respuesta guardada nunca incluye un secreto. Un POST que devuelve uno (registrar un endpoint de webhook, y crear o renovar una clave de API en la app) lleva el secreto solo en la primera respuesta, con secretAlreadyShown: false. Una repetición dentro de las 24 horas responde con el mismo objeto con secret: null y secretAlreadyShown: true.

Si se perdió la primera respuesta, el objeto sigue existiendo (su id está en la repetición). Rota el secreto del endpoint en la app (o elimina el endpoint y regístralo de nuevo), o renueva la clave de API, para obtener un secreto nuevo.

{  "id": "whe_3k8m2q9x7c4v1b6n",  "url": "https://hooks.example.com/dotwick",  "secret": null,  "secretAlreadyShown": true}

Reintentar con seguridad

import { randomUUID } from "node:crypto";// one key per logical operation, reused on every retry of itconst idempotencyKey = randomUUID();for (let attempt = 1; attempt <= 5; attempt++) {  const res = await fetch("https://api.dotwick.com/v1/codes", {    method: "POST",    headers: {      Authorization: `Bearer ${process.env.DOTWICK_API_KEY}`,      "Content-Type": "application/json",      "Idempotency-Key": idempotencyKey,    },    body: JSON.stringify({ name: "Spring menu", content: { type: "url", url: "https://example.com/menu" } }),  });  if (res.ok) break; // a replay answers the first result with Idempotent-Replayed: true  if (res.status !== 429 && res.status < 500) throw new Error((await res.json()).error.message);  const wait = Number(res.headers.get("Retry-After") ?? 2 ** attempt);  await new Promise((r) => setTimeout(r, wait * 1000));}

Rutas que aceptan una clave

Todos los POST excepto la subida multipart POST /v1/assets.