Errors
Errors from the endpoints use one shape with a matching HTTP status. Branch on code, which is stable.
The error object
{
"success": false,
"error": {
"code": "validation_failed",
"message": "Campaign name is required.",
"details": [ { "field": "name", "code": "required", "message": "Name is required." } ],
"requestId": "8b745970b85446088eed2c6b0d7eee6a"
}
}codeis stable: branch on it.messageis for people and can change.detailslists field-level problems when a request fails validation.requestIdidentifies the request: the same value as theX-Correlation-Idresponse header (Request ids). Quote it when you write to support at[email protected].
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 [email protected] 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. |
| 400 | unsupported_version, version_retired | The Ken-Version header, or your key's version, is not a version you can use. See Versioning. |
| 401 | unauthenticated | The request has no valid credential. See 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. |
| 429 | rate_limited, quota_exceeded | You hit a rate limit or a usage quota. Wait the Retry-After seconds. See 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). The body is plain text or{ "error": "Rate limit exceeded" }. Wait and retry, and honorRetry-Afterwhen the response carries it.503: Kenso could not check the key. The body is{ "error": "Authentication is temporarily unavailable" }. Retry after theRetry-Afterseconds.
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 | 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 | The OAuth code is missing, or the CRM did not accept it. |
| 400 | invalid_lookalike | A lookalike filter is not valid. |
| 400 | invalid_member | The member id is not an active member of the workspace. |
| 400 | invalid_phone | The phone number is missing, is not a phone number, or is not one of the person's phones. |
| 400, 409 | invalid_state | 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 | Importing from a LinkedIn URL needs a connected LinkedIn account, and you have none. |
| 400 | linkedin_account_unavailable | The LinkedIn account is not one you connected, is disconnected, or is paused. |
| 400 | lookalike_conflict | The body sends both lookalike filters. |
| 400 | lookalike_not_storable | A lookalike search cannot be saved, proposed or imported this way. |
| 400 | lookalikes_unavailable | Lookalike search is not available right now. |
| 400 | provider_error | The member declined consent in the CRM. |
| 400, 409 | sales_navigator_required | The import needs Sales Navigator, and the LinkedIn account has none. |
| 400 | too_many_seeds | A lookalike filter has too many seeds or negatives. |
| 400 | unsupported | A value is not one Kenso supports, such as an event type that is not in the event log. |
| 400 | unsupported_linkedin_url | Kenso cannot import from this LinkedIn URL. |
| 400 | unsupported_version | The Ken-Version header, or your key's pin, is a date that is not an API version. |
| 400, 413 | validation_failed | A parameter, header or body field is missing or invalid, or the body is too large (413). details names each field. |
| 400 | version_retired | The Ken-Version header, or your key's pin, names a version that is retired. |
| 400 | workspace_required | Your API key reaches several workspaces and the request has no X-Ken-Workspace-Id. |
| 401 | invalid_key | The request sent a Kenso API key, but no active key matches it. |
| 401 | key_expired | The API key passed its expiry date and stopped working. |
| 401 | key_owner_inactive | The member who created the API key is no longer active in Kenso, so the key stopped working. |
| 401 | key_revoked | The API key was revoked in Kenso. |
| 401 | malformed_key | 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 | The request sent no API key. |
| 401 | unauthenticated | The request has no valid credential, or the API key belongs to no member. |
| 402 | calling_limit_reached | The call would pass the workspace's monthly calling spend limit. |
| 402 | dispute_hold | Sending is held while a payment dispute is open. |
| 402 | free_plan_sending_needs_plan | The workspace is on the Free plan, which sends nothing, test emails included. error.refusal has the upgrade to make. |
| 402 | insufficient_credits | The workspace's credits do not cover the action. error.refusal says how short they are. |
| 402 | member_credit_limit_reached | The action would pass your own monthly credit limit in this workspace. error.refusal says what to do. |
| 402 | plan_limit_reached | 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 | This needs a paid plan, or the connection is paused for the plan. |
| 402 | trial_cap_reached | 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. |
| 403 | approval_requires_human | Only a person signed in to the Kenso app can let an agent send on its own. An agent, an API key or the MCP cannot make that change. |
| 403 | feature_disabled | A filter or option in the request needs a feature that is not on for your workspace, such as lookalike search. |
| 403 | forbidden | This caller may not act on this resource. Often the API key is not tied to a member of the workspace. |
| 403 | permission_denied | Your permissions do not allow this. details names the page and level, or the permission, it needs. |
| 404 | not_found | The resource does not exist, was deleted, or is in a workspace you are not a member of. |
| 409 | acknowledgement_required | 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 | Your agent is not connected to your Kenso sandbox. |
| 409 | already_submitted | The list is already waiting for review. |
| 409 | approval_required | Your client has to approve something first. The kinds detail lists what waits, such as copy or lead_list. |
| 409 | blocked | Kenso blocked the current image, so this call cannot replace it. |
| 409 | conflict | The request conflicts with existing data, or with another request on the same resource that is still running. |
| 409 | control_unavailable | There are not enough seed inboxes for the placement test's control group. |
| 409 | crm_account_mismatch | The member authorized a different CRM account than the one this connection uses. |
| 409 | crm_already_connected | The workspace is already connected to another CRM. |
| 409 | crm_sync_disabled | Writing to the CRM is not on for this workspace yet. |
| 409 | demo_workspace | A demo workspace cannot run this. |
| 409 | estimate_changed | More work is waiting than when the run was estimated, so its credit ceiling is now higher. Nothing was held. |
| 409 | image_in_use | The contact already has a sent or queued step that uses this image variable, so it keeps its image. |
| 409 | image_variable_in_use | A step of the campaign still uses the image variable's token. |
| 409 | image_variable_limit | The campaign already has 5 image variables. |
| 409 | import_pending | The CRM connection's first import has not finished yet. |
| 409 | import_running | An import is already running. |
| 409 | in_progress | A send under this Idempotency-Key is still running. |
| 409 | link_host_required | The workspace has no tracking link host. |
| 409 | linkedin_seat_required | 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 | Kenso is still writing this localization. |
| 409 | localization_not_approvable | 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 | The member already has a phone number. |
| 409 | needs_reconnect | The CRM refused Kenso's access. |
| 409 | no_email_recipients | Every recipient of the share is a name with no email address, so there is nobody to email. |
| 409 | no_numbers_available | The search found no phone number to buy. |
| 409 | no_voicemail | The request sent no voicemailId, and you have no voicemail greeting. |
| 409 | not_connected | The workspace has no working connection to that service. |
| 409 | not_held | 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 | The workspace already has five phone numbers, the most it may have. |
| 409 | outcome_unknown | Kenso cannot tell whether the earlier send under this Idempotency-Key went out, and never sends it again. |
| 409 | provider_key_missing | The workspace has no API key for the voice provider, or cannot use its own keys yet. |
| 409 | reconnect_required | The connection the import needs, such as your Google connection, is missing or expired. |
| 409 | reply_not_sent | The email reply under this Idempotency-Key failed or was cancelled, and never went out. |
| 409 | resource_exhausted | The workspace has the most it may have of this, such as 50 active webhook subscriptions. |
| 409 | rights_confirmation_required | The list has members from a CSV upload, and nobody confirmed the right to share them. |
| 409 | run_active | A run is already live in your sandbox. |
| 409 | run_in_progress | A build is already queued or running. |
| 409 | runs_on_agent | The workspace gave this flow to its own agent, so Kenso's AI does not run it. |
| 409 | scope_required | The connection's token lacks the read scopes, or the access to the base, that the import needs. |
| 409 | shared_host_link_frozen | The link has tracking URLs on a host Kenso shares between workspaces, so its destination cannot change. |
| 409 | sheet_not_shared | The sheet does not exist, or was not picked for Kenso. |
| 409 | variable_key_taken | Another variable of the campaign already uses the key, or the key is reserved. |
| 409 | version_conflict | Someone saved a newer version since you read it. The error carries the current version. |
| 409 | version_html_missing | That version's page is no longer stored. |
| 409 | video_in_use | 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 | Kenso is still making the audio. |
| 409 | voicemail_limit_reached | You already have five voicemail greetings. |
| 409 | website_missing | Neither mainSiteUrl nor the workspace website is set. |
| 409 | wrong_kind | The image variable is the other kind for this call: shared or per_prospect. |
| 410 | gone | The resource is gone for good, such as voice note audio Kenso deleted after 90 days. |
| 410 | share_expired | The share has expired. |
| 410 | share_inactive | The share link was turned off for good. |
| 422 | call_refused | Kenso refused the call. details[0].code names the reason, such as outside_calling_hours, opted_out or daily_limit. |
| 422 | export_limit_exceeded | 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 | The export file would be larger than 512 MB. |
| 422 | filter_required | The search sets no filter. |
| 422 | guardrail_violation | The send breaks one of the workspace's contact limits. |
| 422 | idempotency_key_reused | The Idempotency-Key was already used with a different request. |
| 422 | invalid_cursor | The cursor did not come from a previous page of this list. |
| 422 | no_steps_found | The text holds no step Kenso can run. |
| 422 | no_usable_seeds | Kenso could not use any seed of the lookalike search. lookalikeSeeds says how it read each one. |
| 422 | role_address | 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 | unprocessable | The request is well formed but cannot apply, such as setting a person on a thread that has no contact. |
| 422 | unsupported_link | No link in the request is a social link Kenso can read. |
| 422 | validation_error | 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 | 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 | 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 | 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 | Too many requests: yours, or Kenso's to a service it calls for you. |
| 500 | internal_error | The request failed inside Kenso. |
| 502 | provider_rejected | The provider refused the workspace's API key. |
| 503 | auth_unavailable | Kenso could not check the API key just now. |
| 503 | crm_unavailable | Kenso cannot reach the CRM right now. |
| 503 | provider_unavailable | A service Kenso needs for this request is not set up, or did not answer. |
| 503 | service_unavailable | Kenso cannot serve the request right now. |
| 503 | social_data_unavailable | Social data could not be read right now. |
| 503 | try_again | Another action on the same thing is still running, such as another call starting. |
| 503 | voice_notes_unavailable | Voice notes are not available right now, or the voice provider did not answer. |
| 504 | upstream_timeout | A service Kenso called for this request took too long to answer. |
More guides
AuthenticationWorkspacesVersioningPaginationRate limitsIdempotencyWebhooksChangelogAPI reference