Idempotency

Every write (POST, PUT, PATCH) accepts the X-Idempotency-Key header. With it, repeating the same request (because of a timeout, a network drop, an automatic retry) does not create anything twice: the API returns the original response.

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

Rules

Rule	Value
Key format	opaque text, 1 to 255 characters
Validity	24 hours
Scope	the organization: the same key in different organizations does not collide
What identifies the request	method, path, query and body

Situation	Response
New key	the request runs normally, and the response is stored
Same key, same request	the original response (status and body), with `X-Idempotent-Replay: true`
Same key, different request	`409 IDEMPOTENCY_KEY_REUSED`
Same key while the first is still processing	`409 IDEMPOTENCY_REQUEST_IN_PROGRESS`

Generate one key per business operation (for example, run-<date>-<task>), not per attempt: using the same key on every retry is what makes the retry safe.

The run endpoint accepts the same header, with the same rules.

Rules​

Rules