Idempotencia

Toda escritura (POST, PUT, PATCH) acepta el header X-Idempotency-Key. Con él, repetir la misma solicitud (por un timeout, una caída de red, un retry automático) no crea nada dos veces: la API devuelve la respuesta original.

curl -H "Authorization: Bearer $KOBANA_TOKEN" \
  -H "Content-Type: application/json" \
  -H "X-Idempotency-Key: disparo-2026-10-31-baixa" \
  -X POST https://api.kadu.ia.br/v1/tasks/2f1c…/run \
  -d '{"environment_id":"8a40…","reference_date":"2026-10-30"}'

Reglas

Regla	Valor
Formato de la clave	texto opaco, de 1 a 255 caracteres
Vigencia	24 horas
Alcance	la organización: la misma clave en organizaciones distintas no colisiona
Qué identifica la solicitud	método, ruta, query y cuerpo

Situación	Respuesta
Clave nueva	la solicitud corre normalmente, y la respuesta queda guardada
Misma clave, misma solicitud	la respuesta original (estado y cuerpo), con `X-Idempotent-Replay: true`
Misma clave, solicitud distinta	`409 IDEMPOTENCY_KEY_REUSED`
Misma clave mientras la primera aún se procesa	`409 IDEMPOTENCY_REQUEST_IN_PROGRESS`

Genera una clave por operación de negocio (por ejemplo, disparo-<fecha>-<tarea>), y no por intento: es la misma clave en todos los retries lo que vuelve seguro el retry.

El endpoint de lanzamiento acepta el mismo header, con las mismas reglas.

Reglas​

Reglas