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

# Errors

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

Errors from the endpoints use one shape with a matching HTTP status. Branch on `code`, which is stable.

## The error object

```json
{
  "success": false,
  "error": {
    "code": "validation_failed",
    "message": "Campaign name is required.",
    "details": [ { "field": "name", "code": "required", "message": "Name is required." } ],
    "requestId": "8b745970b85446088eed2c6b0d7eee6a"
  }
}
```

- `code` is stable: branch on it.
- `message` is for people and can change.
- `details` lists field-level problems when a request fails validation.
- `requestId` identifies the request: the same value as the `X-Correlation-Id` response header ([Request ids](#request-id)). Quote it when you write to support at `contact@ken.so`.

## Request ids

Every response carries its request id in the `X-Correlation-Id` header, errors or not. When the body is the error object above, its `requestId` is the same value. The gateway's `401` and `429` have no error object, so the header is their only id. Browsers can read the header from a cross-origin response.

To set the id yourself, send an `X-Correlation-Id` header of up to 64 letters, digits, `.`, `_` or `-`. Kenso uses your value and returns it, so you can match a response to your own logs. Otherwise Kenso makes one.

When a call goes wrong, write to [contact@ken.so](mailto:contact@ken.so) with its request id, and we can find that call in our logs.

## Codes

Many operations answer with a more specific `code` than the ones below, and list those codes in their description.

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | `validation_failed` | A parameter, body field or header is missing or invalid. `details` names it. |
| 400 | `workspace_required` | Your key reaches several workspaces and the request has no `X-Ken-Workspace-Id`. See [Workspaces](/docs/workspaces). |
| 400 | `unsupported_version`, `version_retired` | The `Ken-Version` header, or your key's version, is not a version you can use. See [Versioning](/docs/versioning). |
| 401 | `unauthenticated` | The request has no valid credential. See [Authentication](/docs/authentication). |
| 402 | `plan_limit_reached` | Your plan or a usage limit does not allow this. `error.refusal` names the limit and how to lift it. |
| 403 | `permission_denied` | Your permissions in the workspace do not allow this call. `details` names the permission it needs. |
| 403 | `forbidden` | The caller may not act on this resource. |
| 404 | `not_found` | The resource does not exist, or it is in a workspace you are not a member of. |
| 409 | `conflict`, `invalid_state` | The request conflicts with existing data, or the resource is in a state that does not allow the action. |
| 409 | `in_progress`, `outcome_unknown` | Starting a thread: a send under this `Idempotency-Key` is still running, or Kenso cannot tell whether the email went out. The operation's description says what to do. |
| 422 | `idempotency_key_reused` | The `Idempotency-Key` was already used with a different request. See [Idempotency](/docs/idempotency). |
| 429 | `rate_limited`, `quota_exceeded` | You hit a rate limit or a usage quota. Wait the `Retry-After` seconds. See [Rate limits](/docs/rate-limits). |
| 500 | `internal_error` | The request failed in Kenso. |
| 503 | `service_unavailable` | Kenso cannot serve the request right now, or a repeat with the same `Idempotency-Key` arrived while the first request was still running. Retry after the `Retry-After` seconds. |

## 401, 429 and 503 from the gateway

Some `401`, `429` and `503` responses come from the authentication and rate-limit layers in front of the endpoints. They do not use the error object, so branch on the HTTP status for them:

- `401`: the API key is missing, invalid or revoked. The body is `{ "error": "Invalid or revoked API key" }` or empty.
- `429`: your key or your IP sent too many requests, or a call went over its operation's own limit (see [Rate limits](/docs/rate-limits)). The body is plain text or `{ "error": "Rate limit exceeded" }`. Wait and retry, and honor `Retry-After` when the response carries it.
- `503`: Kenso could not check the key. The body is `{ "error": "Authentication is temporarily unavailable" }`. Retry after the `Retry-After` seconds.

## Every error code

Every code the API documents, with its status. Each one has a page on what it means and how to fix it.

| Status | Code | Meaning |
| --- | --- | --- |
| 400 | [`callback_verification_failed`](/docs/errors/callback_verification_failed.md) | The webhook URL did not pass Kenso's check. `details[0].code` says why: `connection_refused`, `timeout`, `tls_error`, `http_4xx`, `http_5xx` or `challenge_failed`. |
| 400 | [`exchange_failed`](/docs/errors/exchange_failed.md) | The OAuth `code` is missing, or the CRM did not accept it. |
| 400 | [`invalid_lookalike`](/docs/errors/invalid_lookalike.md) | A lookalike filter is not valid. |
| 400 | [`invalid_member`](/docs/errors/invalid_member.md) | The member id is not an active member of the workspace. |
| 400 | [`invalid_phone`](/docs/errors/invalid_phone.md) | The phone number is missing, is not a phone number, or is not one of the person's phones. |
| 400, 409 | [`invalid_state`](/docs/errors/invalid_state.md) | The resource is in a state that does not allow this action, such as a request that is no longer pending or a disconnected connection. An OAuth step answers `400` when its state is missing or expired. |
| 400 | [`linkedin_account_required`](/docs/errors/linkedin_account_required.md) | Importing from a LinkedIn URL needs a connected LinkedIn account, and you have none. |
| 400 | [`linkedin_account_unavailable`](/docs/errors/linkedin_account_unavailable.md) | The LinkedIn account is not one you connected, is disconnected, or is paused. |
| 400 | [`lookalike_conflict`](/docs/errors/lookalike_conflict.md) | The body sends both lookalike filters. |
| 400 | [`lookalike_not_storable`](/docs/errors/lookalike_not_storable.md) | A lookalike search cannot be saved, proposed or imported this way. |
| 400 | [`lookalikes_unavailable`](/docs/errors/lookalikes_unavailable.md) | Lookalike search is not available right now. |
| 400 | [`owner_not_member`](/docs/errors/owner_not_member.md) | The owner is not an active member of the workspace, or is a network member, who cannot own a line. `details[0].code` is `network_member` for a network member. |
| 400 | [`provider_error`](/docs/errors/provider_error.md) | The member declined consent in the CRM. |
| 400, 409 | [`sales_navigator_required`](/docs/errors/sales_navigator_required.md) | The import needs Sales Navigator, and the LinkedIn account has none. |
| 400 | [`too_many_seeds`](/docs/errors/too_many_seeds.md) | A lookalike filter has too many seeds or negatives. |
| 400 | [`unsupported`](/docs/errors/unsupported.md) | A value is not one Kenso supports, such as an event type that is not in the event log. |
| 400 | [`unsupported_linkedin_url`](/docs/errors/unsupported_linkedin_url.md) | Kenso cannot import from this LinkedIn URL. |
| 400 | [`unsupported_version`](/docs/errors/unsupported_version.md) | The `Ken-Version` header is not an API version: an unknown date, or a typo such as `2026-11-2` or `v1.1`. `details` lists the versions you can send. |
| 400, 413 | [`validation_failed`](/docs/errors/validation_failed.md) | A parameter, header or body field is missing or invalid, or the body is too large (`413`). `details` names each field. |
| 400 | [`version_retired`](/docs/errors/version_retired.md) | The `Ken-Version` header, or your key's pin, names a version that is retired. |
| 400 | [`workspace_required`](/docs/errors/workspace_required.md) | Your API key reaches several workspaces and the request has no `X-Ken-Workspace-Id`. |
| 401 | [`invalid_key`](/docs/errors/invalid_key.md) | The request sent a Kenso API key, but no active key matches it. |
| 401 | [`key_expired`](/docs/errors/key_expired.md) | The API key passed its expiry date and stopped working. |
| 401 | [`key_owner_inactive`](/docs/errors/key_owner_inactive.md) | The member who created the API key is no longer active in Kenso, so the key stopped working. |
| 401 | [`key_revoked`](/docs/errors/key_revoked.md) | The API key was revoked in Kenso. |
| 401 | [`malformed_key`](/docs/errors/malformed_key.md) | The credential is not a Kenso API key sent the expected way: the `Authorization` header does not start with `Bearer`, the key is in `X-Api-Key`, or the value is not shaped like a key. |
| 401 | [`missing_credential`](/docs/errors/missing_credential.md) | The request sent no API key. |
| 401 | [`unauthenticated`](/docs/errors/unauthenticated.md) | The request has no valid credential, or the API key belongs to no member. |
| 402 | [`calling_limit_reached`](/docs/errors/calling_limit_reached.md) | The call would pass the workspace's monthly calling spend limit. |
| 402 | [`dispute_hold`](/docs/errors/dispute_hold.md) | Sending is held while a payment dispute is open. |
| 402 | [`free_credits_not_eligible`](/docs/errors/free_credits_not_eligible.md) | Only free or bonus credits would cover the action, and they cannot pay for it. `error.refusal` says what to add. |
| 402 | [`free_plan_sending_needs_plan`](/docs/errors/free_plan_sending_needs_plan.md) | The workspace is on the Free plan, which sends nothing, test emails included. `error.refusal` has the upgrade to make. |
| 402 | [`insufficient_credits`](/docs/errors/insufficient_credits.md) | The workspace's credits do not cover the action. `error.refusal` says how short they are. |
| 402 | [`member_credit_limit_reached`](/docs/errors/member_credit_limit_reached.md) | The action would pass your own monthly credit limit in this workspace. `error.refusal` says what to do. |
| 402 | [`plan_limit_reached`](/docs/errors/plan_limit_reached.md) | Your plan or a usage limit does not allow this, for example the workspace is out of credits. `error.refusal` names the limit and how to lift it. |
| 402 | [`plan_required`](/docs/errors/plan_required.md) | This needs a paid plan, or the connection is paused for the plan. |
| 402 | [`trial_cap_reached`](/docs/errors/trial_cap_reached.md) | The workspace is on the Growth trial and reached one of its caps, such as its one LinkedIn or WhatsApp account or its 1,000 Kenso database contacts in any 24 hours. `error.refusal` names the cap. |
| 402 | [`workspace_read_only`](/docs/errors/workspace_read_only.md) | The workspace is read-only: it has no active plan, such as after its trial ended, or its Kenso Lifetime license is no longer active. Reads still work, but most writes are refused. `error.refusal` has the code `WORKSPACE_READ_ONLY` and the remedy. |
| 403 | [`approval_requires_human`](/docs/errors/approval_requires_human.md) | Only a person signed in to the Kenso app can let Ken send or accept on its own. An agent, an API key or the MCP cannot make that change. |
| 403, 409 | [`demo_workspace`](/docs/errors/demo_workspace.md) | A demo workspace cannot run this. |
| 403 | [`feature_disabled`](/docs/errors/feature_disabled.md) | A filter or option in the request needs a feature that is not on for your workspace, such as lookalike search. |
| 403 | [`forbidden`](/docs/errors/forbidden.md) | This caller may not act on this resource. Often the API key is not tied to a member of the workspace. |
| 403 | [`permission_denied`](/docs/errors/permission_denied.md) | Your permissions do not allow this. `details` names the page and level, or the permission, it needs. |
| 404 | [`not_found`](/docs/errors/not_found.md) | The resource does not exist, was deleted, or is in a workspace you are not a member of. |
| 409 | [`acknowledgement_required`](/docs/errors/acknowledgement_required.md) | The campaign has contacts in a country whose cold email rules ask for consent first, and nobody has acknowledged those rules for this campaign. |
| 409 | [`agent_not_connected`](/docs/errors/agent_not_connected.md) | Your agent is not connected to your Kenso sandbox. |
| 409 | [`already_submitted`](/docs/errors/already_submitted.md) | The list is already waiting for review. |
| 409 | [`approval_required`](/docs/errors/approval_required.md) | Your client has to approve something first. The `kinds` detail lists what waits, such as `copy` or `lead_list`. |
| 409 | [`blocked`](/docs/errors/blocked.md) | Kenso blocked the current image, so this call cannot replace it. |
| 409 | [`conflict`](/docs/errors/conflict.md) | The request conflicts with existing data, or with another request on the same resource that is still running. |
| 409 | [`control_unavailable`](/docs/errors/control_unavailable.md) | There are not enough seed inboxes for the placement test's control group. |
| 409 | [`crm_account_mismatch`](/docs/errors/crm_account_mismatch.md) | The member authorized a different CRM account than the one this connection uses. |
| 409 | [`crm_already_connected`](/docs/errors/crm_already_connected.md) | The workspace is already connected to another CRM. |
| 409 | [`crm_sync_disabled`](/docs/errors/crm_sync_disabled.md) | Writing to the CRM is not on for this workspace yet. |
| 409 | [`estimate_changed`](/docs/errors/estimate_changed.md) | More work is waiting than when the run was estimated, so its credit ceiling is now higher. Nothing was held. |
| 409 | [`image_in_use`](/docs/errors/image_in_use.md) | The contact already has a sent or queued step that uses this image variable, so it keeps its image. |
| 409 | [`image_variable_in_use`](/docs/errors/image_variable_in_use.md) | A step of the campaign still uses the image variable's token. |
| 409 | [`image_variable_limit`](/docs/errors/image_variable_limit.md) | The campaign already has 5 image variables. |
| 409 | [`imessage_line_gone`](/docs/errors/imessage_line_gone.md) | The iMessage line can no longer send: it was released, failed or never activated. Nothing goes on its threads again. |
| 409 | [`imessage_line_limit_reached`](/docs/errors/imessage_line_limit_reached.md) | The workspace already has as many iMessage lines as it may have, 10 by default. |
| 409 | [`imessage_line_owner_left`](/docs/errors/imessage_line_owner_left.md) | The owner of the iMessage line can't send from it anymore: a former member or a network member. |
| 409 | [`import_pending`](/docs/errors/import_pending.md) | The CRM connection's first import has not finished yet. |
| 409 | [`import_running`](/docs/errors/import_running.md) | An import is already running. |
| 409 | [`in_progress`](/docs/errors/in_progress.md) | A send under this `Idempotency-Key` is still running. |
| 409 | [`link_host_required`](/docs/errors/link_host_required.md) | The workspace has no tracking link host. |
| 409 | [`linkedin_seat_required`](/docs/errors/linkedin_seat_required.md) | This needs your own connected LinkedIn seat, and none can read right now: you have none, or it is paused, throttled or reported unavailable by LinkedIn. |
| 409 | [`localization_generating`](/docs/errors/localization_generating.md) | Kenso is still writing this localization. |
| 409 | [`localization_not_approvable`](/docs/errors/localization_not_approvable.md) | The localization is not a current draft that passed its checks. The detail code says why: `not_draft`, `stale`, `qa_failed` or `score_below_threshold`. |
| 409 | [`member_already_has_number`](/docs/errors/member_already_has_number.md) | The member already has a phone number. |
| 409 | [`needs_reconnect`](/docs/errors/needs_reconnect.md) | The CRM refused Kenso's access. |
| 409 | [`no_email_recipients`](/docs/errors/no_email_recipients.md) | Every recipient of the share is a name with no email address, so there is nobody to email. |
| 409 | [`no_numbers_available`](/docs/errors/no_numbers_available.md) | The search found no phone number to buy. |
| 409 | [`no_voicemail`](/docs/errors/no_voicemail.md) | The request sent no `voicemailId`, and you have no voicemail greeting. |
| 409 | [`not_connected`](/docs/errors/not_connected.md) | The workspace has no working connection to that service. |
| 409 | [`not_held`](/docs/errors/not_held.md) | The contact has no hold in this campaign. It was never held, was already approved, or its lines were written again. |
| 409 | [`number_limit_reached`](/docs/errors/number_limit_reached.md) | The workspace already has five phone numbers, the most it may have. |
| 409 | [`outcome_unknown`](/docs/errors/outcome_unknown.md) | Kenso cannot tell whether the earlier send under this `Idempotency-Key` went out, and never sends it again. |
| 409 | [`person_refused`](/docs/errors/person_refused.md) | The person said no, and nothing since takes it back (a reply that is not a refusal, an accepted connection or a booked meeting). Kenso does not text them for an agent or API key, or in words Ken writes. |
| 409 | [`provider_key_missing`](/docs/errors/provider_key_missing.md) | The workspace has no API key for the voice provider, or cannot use its own keys yet. |
| 409 | [`reconnect_required`](/docs/errors/reconnect_required.md) | The connection the import needs, such as your Google connection, is missing or expired. |
| 409 | [`reply_not_sent`](/docs/errors/reply_not_sent.md) | The email reply under this `Idempotency-Key` failed or was cancelled, and never went out. |
| 409 | [`resource_exhausted`](/docs/errors/resource_exhausted.md) | The workspace has the most it may have of this, such as 50 active webhook subscriptions. |
| 409 | [`rights_confirmation_required`](/docs/errors/rights_confirmation_required.md) | The list has members from a CSV upload, and nobody confirmed the right to share them. |
| 409 | [`run_active`](/docs/errors/run_active.md) | A run is already live in your sandbox. |
| 409 | [`run_in_progress`](/docs/errors/run_in_progress.md) | A build is already queued or running. |
| 409 | [`runs_on_agent`](/docs/errors/runs_on_agent.md) | The workspace gave this flow to its own agent, so Kenso's AI does not run it. |
| 409 | [`scope_required`](/docs/errors/scope_required.md) | The connection's token lacks the read scopes, or the access to the base, that the import needs. |
| 409 | [`shared_host_link_frozen`](/docs/errors/shared_host_link_frozen.md) | The link has tracking URLs on a host Kenso shares between workspaces, so its destination cannot change. |
| 409 | [`sheet_not_shared`](/docs/errors/sheet_not_shared.md) | The sheet does not exist, or was not picked for Kenso. |
| 409 | [`variable_key_taken`](/docs/errors/variable_key_taken.md) | Another variable of the campaign already uses the key, or the key is reserved. |
| 409 | [`version_conflict`](/docs/errors/version_conflict.md) | Someone saved a newer version since you read it. The error carries the current version. |
| 409 | [`version_html_missing`](/docs/errors/version_html_missing.md) | That version's page is no longer stored. |
| 409 | [`video_in_use`](/docs/errors/video_in_use.md) | A sent or queued email step uses the contact's current video, so it cannot change. The old video stays. |
| 409 | [`voice_note_not_ready`](/docs/errors/voice_note_not_ready.md) | Kenso is still making the audio. |
| 409 | [`voicemail_limit_reached`](/docs/errors/voicemail_limit_reached.md) | You already have five voicemail greetings. |
| 409 | [`website_missing`](/docs/errors/website_missing.md) | Neither `mainSiteUrl` nor the workspace website is set. |
| 409 | [`workspace_closing`](/docs/errors/workspace_closing.md) | The workspace is closing, or was deleted, so it takes no new orders. |
| 409 | [`wrong_kind`](/docs/errors/wrong_kind.md) | The image variable is the other kind for this call: `shared` or `per_prospect`. |
| 410 | [`gone`](/docs/errors/gone.md) | The resource is gone for good, such as voice note audio Kenso deleted after 90 days. |
| 410 | [`share_expired`](/docs/errors/share_expired.md) | The share has expired. |
| 410 | [`share_inactive`](/docs/errors/share_inactive.md) | The share link was turned off for good. |
| 422 | [`attachment_too_large`](/docs/errors/attachment_too_large.md) | The attachment is over 10,000,000 bytes, more than Kenso serves. |
| 422 | [`call_refused`](/docs/errors/call_refused.md) | Kenso refused the call. `details[0].code` names the reason, such as `outside_calling_hours`, `opted_out` or `daily_limit`. |
| 422 | [`export_limit_exceeded`](/docs/errors/export_limit_exceeded.md) | More rows match than this export may return. `details[0].count` is how many matched and `details[0].limit` the most the export returns. |
| 422 | [`export_too_large`](/docs/errors/export_too_large.md) | The export file would be larger than 512 MB. |
| 422 | [`filter_required`](/docs/errors/filter_required.md) | The search sets no filter. |
| 422 | [`guardrail_violation`](/docs/errors/guardrail_violation.md) | The send breaks one of the workspace's contact limits. |
| 422 | [`idempotency_key_reused`](/docs/errors/idempotency_key_reused.md) | The `Idempotency-Key` was already used with a different request. |
| 422 | [`invalid_cursor`](/docs/errors/invalid_cursor.md) | The cursor did not come from a previous page of this list. |
| 422 | [`no_steps_found`](/docs/errors/no_steps_found.md) | The text holds no step Kenso can run. |
| 422 | [`no_usable_seeds`](/docs/errors/no_usable_seeds.md) | Kenso could not use any seed of the lookalike search. `lookalikeSeeds` says how it read each one. |
| 422 | [`role_address`](/docs/errors/role_address.md) | The email is a role address, such as info@, no person matches it, and the body has no LinkedIn URL or real name. Kenso wrote nothing. |
| 422 | [`unfilled_template_key`](/docs/errors/unfilled_template_key.md) | The text still holds a template key nobody filled in, such as `{first_name}`. The detail's `key` names it and `marker` shows it as written. |
| 422 | [`unprocessable`](/docs/errors/unprocessable.md) | The request is well formed but cannot apply, such as setting a person on a thread that has no contact. |
| 422 | [`unsupported_link`](/docs/errors/unsupported_link.md) | No link in the request is a social link Kenso can read. |
| 422 | [`validation_error`](/docs/errors/validation_error.md) | A request field is invalid, such as a filter list with more than 100 items. It means the same as `validation_failed`, with a `422`. |
| 424 | [`provider_key_failed`](/docs/errors/provider_key_failed.md) | The workspace's own social data key failed, or the workspace has no usable key of its own and turned off reads on Kenso's key. |
| 429 | [`daily_limit_reached`](/docs/errors/daily_limit_reached.md) | A daily limit was reached. For social data it is the workspace's limit of records read on Kenso's key, which counts a rolling day. For a Studio doc export it is the connection's limit of new docs shared, which resets at midnight UTC. |
| 429 | [`quota_exceeded`](/docs/errors/quota_exceeded.md) | The workspace used up a quota for this kind of call, such as the daily search quota. `quotaResetAt` or `details` says when it frees up. |
| 429 | [`rate_limited`](/docs/errors/rate_limited.md) | Too many requests: yours, or Kenso's to a service it calls for you. |
| 500 | [`internal_error`](/docs/errors/internal_error.md) | The request failed inside Kenso. |
| 502 | [`provider_rejected`](/docs/errors/provider_rejected.md) | The provider refused the workspace's API key. |
| 503 | [`auth_unavailable`](/docs/errors/auth_unavailable.md) | Kenso could not check the API key just now. |
| 503 | [`crm_unavailable`](/docs/errors/crm_unavailable.md) | Kenso cannot reach the CRM right now. |
| 503 | [`imessage_media_unavailable`](/docs/errors/imessage_media_unavailable.md) | Image uploads for iMessage are not available right now. |
| 503 | [`provider_unavailable`](/docs/errors/provider_unavailable.md) | A service Kenso needs for this request is not set up, or did not answer. |
| 503 | [`service_unavailable`](/docs/errors/service_unavailable.md) | Kenso cannot serve the request right now. |
| 503 | [`social_data_unavailable`](/docs/errors/social_data_unavailable.md) | Social data could not be read right now. |
| 503 | [`try_again`](/docs/errors/try_again.md) | Another action on the same thing is still running, such as another call starting. |
| 503 | [`voice_notes_unavailable`](/docs/errors/voice_notes_unavailable.md) | Voice notes are not available right now, or the voice provider did not answer. |
| 504 | [`upstream_timeout`](/docs/errors/upstream_timeout.md) | A service Kenso called for this request took too long to answer. |

## More guides

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