Idempotency and retries
A timeout can leave you not knowing whether a write happened. Send an Idempotency-Key and the retry is safe: Kenso runs the action once and answers a repeat with the first response.
Operations that list an Idempotency-Key header accept one. Send a unique value, such as a UUID, and send the same value again when you retry. For 24 hours, Kenso answers a repeat of the same request with the first response and the Idempotent-Replayed: true header, and does not run the action again. The same key with a different request answers 422 idempotency_key_reused. Kenso does not store a 5xx response, so a retry after one runs the action again.
429: wait theRetry-Afterseconds, then retry.503: retry after theRetry-Afterseconds, or after a short wait when the header is missing.500and other5xx: retry with a growing wait. On an operation withoutIdempotency-Key, check first whether the write happened, so you do not make it twice.- Other
4xx: fix the request before you send it again.
Make the key once, before the first try, and send the same request with the same key on every retry:
POST /v1/tags/77/assignments HTTP/1.1 Host: api.ken.so Authorization: Bearer <your_api_key> Ken-Version: 2026-11-02 X-Ken-Workspace-Id: 812 Idempotency-Key: 3f6c1a2e-9b4d-4e8a-b7c5-1d2e3f4a5b6c
- Keys are per workspace: the same key in another workspace is another key.
- A repeat that replays the first response carries
Idempotent-Replayed: true. - Each operation's
Idempotency-Keyparameter gives its rules: the status a reused key answers, and which responses are kept.
idempotency_key_reusedidempotency_key_reused409 for a reused key.validation_faileddetails names Idempotency-Key.service_unavailableRetry-After.11 operations list the Idempotency-Key header in the reference: