Una petición que se pierde en la red deja al cliente sin saber si la operación llegó a ejecutarse. Reintentarla puede duplicar el efecto. La cabecera Idempotency-Key resuelve esa ambigüedad: identifica el intento, no la petición.
Idempotency-Key: pedido-4f3a2b1cLa clave la elige quien llama. Admite letras, dígitos, guion y guion bajo, con una longitud de 1 a 255 caracteres; un valor fuera de ese patrón responde 400 con invalid_idempotency_key.
La cabecera es opcional: sin ella, cada petición se ejecuta de forma independiente. Las operaciones que la admiten lo declaran en su página de referencia.
Alcance y vigencia
Cada clave se asocia a la terna cuenta, operación y clave. La misma clave usada contra dos operaciones distintas identifica dos intentos distintos, y dos cuentas pueden usar la misma sin interferir.
El registro se conserva 24 horas. Pasada la ventana, la clave queda libre y una petición con ese valor se trata como nueva.
Comportamiento
| situación | respuesta |
|---|---|
| Clave nueva | La operación se ejecuta con normalidad y su respuesta queda registrada |
| Clave repetida, cuerpo idéntico | Se devuelve la respuesta original con la cabecera Idempotent-Replayed: true. La operación no se ejecuta otra vez |
| Clave repetida, cuerpo distinto | 422 con idempotency_key_reused |
| Clave en curso | 409 con idempotency_key_in_progress: la primera petición sigue ejecutándose |
La reproducción devuelve la respuesta guardada tal cual, incluido su código de estado. Un 201 reproducido sigue siendo un 201, con el mismo cuerpo y el mismo identificador de recurso.
Una petición que termina en error de servidor no deja la clave ocupada: el registro se descarta para que el reintento pueda ejecutarse.
Uso recomendado
La clave debe derivarse del intento de negocio —el identificador del pedido, del lote o de la transacción que se está registrando—, no generarse al azar en cada envío. Una clave aleatoria por reintento anula la protección: cada intento se ve como nuevo.
Un 409 indica que la primera petición sigue en curso; el tratamiento correcto es esperar y volver a consultar, no reenviar con otra clave.