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.
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 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.
Send a key
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.
Errors
| Status | Code | When |
|---|---|---|
| 422 | idempotency_key_reused | The key was already used with a different request. |
| 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. |
Operations that take a key
16 operations list the Idempotency-Key header in the reference:
| Operation | Endpoint | Reused key answers |
|---|---|---|
| Estimate or start a sandbox run | POST /v1/agent-sandbox-runs | 422 |
| Claim agent work | POST /v1/agent-work/claims | 422 |
| Submit agent work answers | POST /v1/agent-work/claims/{claimId}/answers | 422 |
| Rate an AI output | POST /v1/ai-feedback | 422 |
| Launch a campaign | POST /v1/campaigns/{campaignId}/launch | 422 |
| Connect an SMTP inbox | POST /v1/inboxes | 422 |
| Assign a tag to an entity | POST /v1/tags/{tagId}/assignments | 422 |
| Remove a tag from an entity | DELETE /v1/tags/{tagId}/assignments | 422 |
| Assign a tag to many entities | POST /v1/tags/{tagId}/assignments/bulk-create | 422 |
| Remove a tag from many entities | POST /v1/tags/{tagId}/assignments/bulk-delete | 422 |
| Start an email thread | POST /v1/threads | 422 |
| Update a thread | PATCH /v1/threads/{threadId} | 422 |
| Mark all threads read | POST /v1/threads/mark-all-read | 422 |
| Update many threads | POST /v1/threads/bulk-update | 422 |
| Send a reply in a thread | POST /v1/threads/{threadId}/messages | 422 |
| Forward an email thread | POST /v1/threads/{threadId}/forward | 422 |
More guides
AuthenticationWorkspacesVersioningPaginationErrorsRate limitsWebhooksChangelogAPI reference