Skip to Content

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

How it works

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.

Send a key

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.

Errors

StatusCodeWhen
422idempotency_key_reusedThe key was already used with a different request.
400validation_failedThe key is too long, or an operation that needs a key got none. details names Idempotency-Key.
503service_unavailableA repeat arrived while the first request was still running. Retry with the same key after Retry-After.

Operations that take a key

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

OperationEndpointReused key answers
Estimate or start a sandbox runPOST /v1/agent-sandbox-runs422
Claim agent workPOST /v1/agent-work/claims422
Submit agent work answersPOST /v1/agent-work/claims/{claimId}/answers422
Rate an AI outputPOST /v1/ai-feedback422
Launch a campaignPOST /v1/campaigns/{campaignId}/launch422
Connect an SMTP inboxPOST /v1/inboxes422
Assign a tag to an entityPOST /v1/tags/{tagId}/assignments422
Remove a tag from an entityDELETE /v1/tags/{tagId}/assignments422
Assign a tag to many entitiesPOST /v1/tags/{tagId}/assignments/bulk-create422
Remove a tag from many entitiesPOST /v1/tags/{tagId}/assignments/bulk-delete422
Start an email threadPOST /v1/threads422
Update a threadPATCH /v1/threads/{threadId}422
Mark all threads readPOST /v1/threads/mark-all-read422
Update many threadsPOST /v1/threads/bulk-update422
Send a reply in a threadPOST /v1/threads/{threadId}/messages422
Forward an email threadPOST /v1/threads/{threadId}/forward422

More guides

On this page