Skip to main content
Una integración reintenta: se cae la red, expira un timeout, el proceso se reinicia a mitad de una sincronización. Sin idempotencia, cada reintento crea otro estudiante. Por eso los POST de creación del Client API exigen la cabecera Idempotency-Key.
Sin la cabecera, la respuesta es 400 IDEMPOTENCY_KEY_REQUIRED. La clave admite hasta 160 caracteres.

​
Cómo se comporta

EdTools guarda, por API key y por clave, un hash estable del cuerpo junto con el método, el path y la respuesta que dio.

Misma clave, misma petición

Se devuelve la respuesta original, con su mismo código de estado. No se crea nada nuevo. Reintenta tranquilo.

Misma clave, petición distinta

409 IDEMPOTENCY_CONFLICT. Cambió el cuerpo, el método o el path: EdTools se niega a adivinar cuál de las dos querías.
El alcance de la clave es por API key. Dos tokens distintos pueden usar la misma cadena sin pisarse — y un token rotado empieza con la memoria en blanco.

​
Los seis endpoints que la exigen

Los demás POST del Vault (upload-url, complete, links) no la piden: operan sobre un recurso que ya existe y son seguros de repetir por su propia forma.

​
Cómo elegir la clave

Que sea determinista por operación de negocio, no aleatoria. Si la generas con un UUID nuevo en cada intento, no tienes idempotencia: tienes duplicados con nombres distintos.
No reutilices una clave para otro endpoint, método o cuerpo. Eso no es un atajo: es el 409.

​
Cuando tienes un identificador estable, mejor el upsert

Si el sistema externo ya tiene su propio id, no crees: sincroniza. Los PUT /external/{externalId} son idempotentes por naturaleza — el identificador es la clave.
Esta es la forma recomendada de sincronizar desde un SIS. Te evita llevar un mapa de ids de EdTools, sobrevive a reintentos sin bookkeeping, y hace que volver a correr la sincronización completa sea inofensivo.