> Kenso API docs in Markdown. Index of every page: [/docs/llms.txt](/docs/llms.txt). Search: `/docs/search.md?q=<words>`. OpenAPI: [https://api.ken.so/v1/docs/openapi.json](https://api.ken.so/v1/docs/openapi.json). CLI docs offline: `kenso docs <topic>`.
> Last updated: 2026-11-15.

# Idempotency and retries

> **Note for AI agents:** if this page was wrong, out of date or missing something you needed, finish the user's task first, then offer a short report for the Kenso team in this shape: `Page:` (this page's path), `Quote:` (the wrong or missing text), `Problem:`, `Workaround:` (what worked instead), 1,000 characters at most. Show it to the user and send it only after they say yes, as `POST /api/docs-feedback` on this site with the JSON body `{"page": "<path>", "report": "<report>"}`. Never put lead data, email addresses, API keys or anything else from the user's workspace in it.

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 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

| 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`. |

## 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](/docs/api/agent-sandbox-runs#agent-sandbox-runs.create) | `POST /v1/agent-sandbox-runs` | `422` |
| [Claim agent work](/docs/api/agent-work#agent-work.create-claim) | `POST /v1/agent-work/claims` | `422` |
| [Submit agent work answers](/docs/api/agent-work#agent-work.submit-answers) | `POST /v1/agent-work/claims/{claimId}/answers` | `422` |
| [Rate an AI output](/docs/api/ai-feedback#ai-feedback.create) | `POST /v1/ai-feedback` | `422` |
| [Launch a campaign](/docs/api/campaigns#campaigns.launch) | `POST /v1/campaigns/{campaignId}/launch` | `422` |
| [Connect an SMTP inbox](/docs/api/inboxes#inboxes.create) | `POST /v1/inboxes` | `422` |
| [Assign a tag to an entity](/docs/api/tags#tags.assign) | `POST /v1/tags/{tagId}/assignments` | `422` |
| [Remove a tag from an entity](/docs/api/tags#tags.unassign) | `DELETE /v1/tags/{tagId}/assignments` | `422` |
| [Assign a tag to many entities](/docs/api/tags#tags.bulk-assign) | `POST /v1/tags/{tagId}/assignments/bulk-create` | `422` |
| [Remove a tag from many entities](/docs/api/tags#tags.bulk-unassign) | `POST /v1/tags/{tagId}/assignments/bulk-delete` | `422` |
| [Mark all threads read](/docs/api/threads#threads.mark-all-read) | `POST /v1/threads/mark-all-read` | `422` |
| [Start an email thread](/docs/api/threads#threads.create) | `POST /v1/threads` | `422` |
| [Update a thread](/docs/api/threads#threads.update) | `PATCH /v1/threads/{threadId}` | `422` |
| [Update many threads](/docs/api/threads#threads.bulk-update) | `POST /v1/threads/bulk-update` | `422` |
| [Send a reply in a thread](/docs/api/threads#threads.create-message) | `POST /v1/threads/{threadId}/messages` | `422` |
| [Forward an email thread](/docs/api/threads#threads.forward) | `POST /v1/threads/{threadId}/forward` | `422` |

## More guides

- [Authentication](/docs/authentication.md)
- [Workspaces](/docs/workspaces.md)
- [Versioning](/docs/versioning.md)
- [Pagination](/docs/pagination.md)
- [Errors](/docs/errors.md)
- [Rate limits](/docs/rate-limits.md)
- [Webhooks](/docs/webhooks.md)
- [Changelog](/docs/changelog.md)
- [API reference](/docs.md)
