Reintentos seguros

Con Idempotency-Key puedes repetir cualquier POST sin miedo a crear una segunda verificación ni a enviar un segundo código.

Por qué hace falta

Una red inestable puede cortar la respuesta aunque la petición sí llegó. Si reintentas a ciegas, podrías crear dos verificaciones. Con Idempotency-Key, el reintento devuelve exactamente la misma respuesta que la primera vez.

Idempotency-Key: signup-8812-attempt-1

Funciona en los dos endpoints. Es opcional, pero recomendado en toda llamada que tu código pueda repetir.

Cómo se comporta

Situación	Respuesta
Primera vez con esa clave	Se procesa normalmente y se guarda la respuesta.
Misma clave, mismo cuerpo	Se devuelve la respuesta guardada: el mismo estado HTTP y el mismo cuerpo. No se envía nada de nuevo.
Misma clave, cuerpo distinto	`422` con `20010`. La clave ya está atada a otra petición.
Misma clave, la primera petición sigue en curso	`409` con `20010` y un `Retry-After`. Espera y repite.

La clave vale 24 horas y es por cuenta y por entorno: dos cuentas pueden usar la misma sin chocar, y también tus claves test_ y live_.
Admite de 1 a 255 caracteres. Fuera de ese rango responde 400 con 20002.
«Mismo cuerpo» significa el mismo método, la misma ruta y los mismos bytes del cuerpo.
Las respuestas 2xx y 4xx se guardan, 429 incluido: para reintentar tras un límite, usa una clave nueva. Un 5xx no se guarda: puedes reintentar con la misma clave y la petición se procesa de nuevo.
La clave es compartida por los dos endpoints: no reutilices una clave de creación en /check.

Cómo elegir la clave

Usa algo que identifique la intención, no el intento: el mismo valor en cada reintento de la misma acción, y un valor nuevo para cada acción nueva. Un «Reenviar» es una acción nueva y necesita otra clave (por ejemplo signup-8812-send-2): reutilizar la clave de creación repite la primera respuesta y no envía nada. En /check, usa una clave por cada código que escriba tu usuario.

// Una clave por intento de registro, reutilizada en cada reintento de red.
const key = `signup-${signupId}`;

for (let attempt = 0; attempt < 3; attempt++) {
  const response = await fetch(url, {
    method: 'POST',
    headers: { ...headers, 'Idempotency-Key': key },
    body,
  });
  if (response.status < 500) return response;
  await sleep(2 ** attempt * 500);
}

👍
Consejo
Sin Idempotency-Key, Verify igual te protege del doble clic: volver a crear una verificación para un destinatario que ya tiene una activa te devuelve esa misma, con 200. La clave de idempotencia cubre además el caso de la red: la respuesta perdida.