Kenso

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.

Ken-Version: 2026-11-02
Markdown

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 the Retry-After seconds, then retry.
  • 503: retry after the Retry-After seconds, or after a short wait when the header is missing.
  • 500 and other 5xx: retry with a growing wait. On an operation without Idempotency-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:

HTTP
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-Key parameter gives its rules: the status a reused key answers, and which responses are kept.
Status
Code
When
422
idempotency_key_reused
The key was already used with a different request.
409
idempotency_key_reused
The same, on the operations whose reference says they answer 409 for a reused key.
400
validation_failed
The key is too long, or an operation that needs a key got none. details names Idempotency-Key.
503
service_unavailable
A repeat arrived while the first request was still running. Retry with the same key after Retry-After.

11 operations list the Idempotency-Key header in the reference:

Operation
Endpoint
Reused key answers
POST /v1/agent-sandbox-runs
422
POST /v1/agent-work/claims
422
POST /v1/agent-work/claims/{claimId}/answers
422
POST /v1/ai-feedback
422
POST /v1/tags/{tagId}/assignments
422
DELETE /v1/tags/{tagId}/assignments
422
POST /v1/tags/{tagId}/assignments/bulk-create
422
POST /v1/tags/{tagId}/assignments/bulk-delete
422
POST /v1/threads/mark-all-read
422
PATCH /v1/threads/{threadId}
422
POST /v1/threads/bulk-update
422