Skip to Content

Errors

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

Ken-Version: 2026-11-02
Markdown

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

StatusCodeMeaning
400validation_failedA parameter, body field or header is missing or invalid. details names it.
400workspace_requiredYour key reaches several workspaces and the request has no X-Ken-Workspace-Id. See Workspaces.
400unsupported_version, version_retiredThe Ken-Version header, or your key's version, is not a version you can use. See Versioning.
401unauthenticatedThe request has no valid credential. See Authentication.
402plan_limit_reachedYour plan or a usage limit does not allow this. error.refusal names the limit and how to lift it.
403permission_deniedYour permissions in the workspace do not allow this call. details names the permission it needs.
403forbiddenThe caller may not act on this resource.
404not_foundThe resource does not exist, or it is in a workspace you are not a member of.
409conflict, invalid_stateThe request conflicts with existing data, or the resource is in a state that does not allow the action.
409in_progress, outcome_unknownStarting 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.
422idempotency_key_reusedThe Idempotency-Key was already used with a different request. See Idempotency.
429rate_limited, quota_exceededYou hit a rate limit or a usage quota. Wait the Retry-After seconds. See Rate limits.
500internal_errorThe request failed in Kenso.
503service_unavailableKenso 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 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.

StatusCodeMeaning
400callback_verification_failedThe 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.
400exchange_failedThe OAuth code is missing, or the CRM did not accept it.
400invalid_lookalikeA lookalike filter is not valid.
400invalid_memberThe member id is not an active member of the workspace.
400invalid_phoneThe phone number is missing, is not a phone number, or is not one of the person's phones.
400, 409invalid_stateThe 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.
400linkedin_account_requiredImporting from a LinkedIn URL needs a connected LinkedIn account, and you have none.
400linkedin_account_unavailableThe LinkedIn account is not one you connected, is disconnected, or is paused.
400lookalike_conflictThe body sends both lookalike filters.
400lookalike_not_storableA lookalike search cannot be saved, proposed or imported this way.
400lookalikes_unavailableLookalike search is not available right now.
400provider_errorThe member declined consent in the CRM.
400, 409sales_navigator_requiredThe import needs Sales Navigator, and the LinkedIn account has none.
400too_many_seedsA lookalike filter has too many seeds or negatives.
400unsupportedA value is not one Kenso supports, such as an event type that is not in the event log.
400unsupported_linkedin_urlKenso cannot import from this LinkedIn URL.
400unsupported_versionThe Ken-Version header, or your key's pin, is a date that is not an API version.
400, 413validation_failedA parameter, header or body field is missing or invalid, or the body is too large (413). details names each field.
400version_retiredThe Ken-Version header, or your key's pin, names a version that is retired.
400workspace_requiredYour API key reaches several workspaces and the request has no X-Ken-Workspace-Id.
401invalid_keyThe request sent a Kenso API key, but no active key matches it.
401key_expiredThe API key passed its expiry date and stopped working.
401key_owner_inactiveThe member who created the API key is no longer active in Kenso, so the key stopped working.
401key_revokedThe API key was revoked in Kenso.
401malformed_keyThe 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.
401missing_credentialThe request sent no API key.
401unauthenticatedThe request has no valid credential, or the API key belongs to no member.
402calling_limit_reachedThe call would pass the workspace's monthly calling spend limit.
402dispute_holdSending is held while a payment dispute is open.
402free_plan_sending_needs_planThe workspace is on the Free plan, which sends nothing, test emails included. error.refusal has the upgrade to make.
402insufficient_creditsThe workspace's credits do not cover the action. error.refusal says how short they are.
402member_credit_limit_reachedThe action would pass your own monthly credit limit in this workspace. error.refusal says what to do.
402plan_limit_reachedYour 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.
402plan_requiredThis needs a paid plan, or the connection is paused for the plan.
402trial_cap_reachedThe 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.
403approval_requires_humanOnly 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.
403feature_disabledA filter or option in the request needs a feature that is not on for your workspace, such as lookalike search.
403forbiddenThis caller may not act on this resource. Often the API key is not tied to a member of the workspace.
403permission_deniedYour permissions do not allow this. details names the page and level, or the permission, it needs.
404not_foundThe resource does not exist, was deleted, or is in a workspace you are not a member of.
409acknowledgement_requiredThe campaign has contacts in a country whose cold email rules ask for consent first, and nobody has acknowledged those rules for this campaign.
409agent_not_connectedYour agent is not connected to your Kenso sandbox.
409already_submittedThe list is already waiting for review.
409approval_requiredYour client has to approve something first. The kinds detail lists what waits, such as copy or lead_list.
409blockedKenso blocked the current image, so this call cannot replace it.
409conflictThe request conflicts with existing data, or with another request on the same resource that is still running.
409control_unavailableThere are not enough seed inboxes for the placement test's control group.
409crm_account_mismatchThe member authorized a different CRM account than the one this connection uses.
409crm_already_connectedThe workspace is already connected to another CRM.
409crm_sync_disabledWriting to the CRM is not on for this workspace yet.
409demo_workspaceA demo workspace cannot run this.
409estimate_changedMore work is waiting than when the run was estimated, so its credit ceiling is now higher. Nothing was held.
409image_in_useThe contact already has a sent or queued step that uses this image variable, so it keeps its image.
409image_variable_in_useA step of the campaign still uses the image variable's token.
409image_variable_limitThe campaign already has 5 image variables.
409import_pendingThe CRM connection's first import has not finished yet.
409import_runningAn import is already running.
409in_progressA send under this Idempotency-Key is still running.
409link_host_requiredThe workspace has no tracking link host.
409linkedin_seat_requiredThis 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.
409localization_generatingKenso is still writing this localization.
409localization_not_approvableThe localization is not a current draft that passed its checks. The detail code says why: not_draft, stale, qa_failed or score_below_threshold.
409member_already_has_numberThe member already has a phone number.
409needs_reconnectThe CRM refused Kenso's access.
409no_email_recipientsEvery recipient of the share is a name with no email address, so there is nobody to email.
409no_numbers_availableThe search found no phone number to buy.
409no_voicemailThe request sent no voicemailId, and you have no voicemail greeting.
409not_connectedThe workspace has no working connection to that service.
409not_heldThe contact has no hold in this campaign. It was never held, was already approved, or its lines were written again.
409number_limit_reachedThe workspace already has five phone numbers, the most it may have.
409outcome_unknownKenso cannot tell whether the earlier send under this Idempotency-Key went out, and never sends it again.
409provider_key_missingThe workspace has no API key for the voice provider, or cannot use its own keys yet.
409reconnect_requiredThe connection the import needs, such as your Google connection, is missing or expired.
409reply_not_sentThe email reply under this Idempotency-Key failed or was cancelled, and never went out.
409resource_exhaustedThe workspace has the most it may have of this, such as 50 active webhook subscriptions.
409rights_confirmation_requiredThe list has members from a CSV upload, and nobody confirmed the right to share them.
409run_activeA run is already live in your sandbox.
409run_in_progressA build is already queued or running.
409runs_on_agentThe workspace gave this flow to its own agent, so Kenso's AI does not run it.
409scope_requiredThe connection's token lacks the read scopes, or the access to the base, that the import needs.
409shared_host_link_frozenThe link has tracking URLs on a host Kenso shares between workspaces, so its destination cannot change.
409sheet_not_sharedThe sheet does not exist, or was not picked for Kenso.
409variable_key_takenAnother variable of the campaign already uses the key, or the key is reserved.
409version_conflictSomeone saved a newer version since you read it. The error carries the current version.
409version_html_missingThat version's page is no longer stored.
409video_in_useA sent or queued email step uses the contact's current video, so it cannot change. The old video stays.
409voice_note_not_readyKenso is still making the audio.
409voicemail_limit_reachedYou already have five voicemail greetings.
409website_missingNeither mainSiteUrl nor the workspace website is set.
409wrong_kindThe image variable is the other kind for this call: shared or per_prospect.
410goneThe resource is gone for good, such as voice note audio Kenso deleted after 90 days.
410share_expiredThe share has expired.
410share_inactiveThe share link was turned off for good.
422call_refusedKenso refused the call. details[0].code names the reason, such as outside_calling_hours, opted_out or daily_limit.
422export_limit_exceededMore rows match than this export may return. details[0].count is how many matched and details[0].limit the most the export returns.
422export_too_largeThe export file would be larger than 512 MB.
422filter_requiredThe search sets no filter.
422guardrail_violationThe send breaks one of the workspace's contact limits.
422idempotency_key_reusedThe Idempotency-Key was already used with a different request.
422invalid_cursorThe cursor did not come from a previous page of this list.
422no_steps_foundThe text holds no step Kenso can run.
422no_usable_seedsKenso could not use any seed of the lookalike search. lookalikeSeeds says how it read each one.
422role_addressThe 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.
422unprocessableThe request is well formed but cannot apply, such as setting a person on a thread that has no contact.
422unsupported_linkNo link in the request is a social link Kenso can read.
422validation_errorA request field is invalid, such as a filter list with more than 100 items. It means the same as validation_failed, with a 422.
424provider_key_failedThe 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.
429daily_limit_reachedA 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.
429quota_exceededThe workspace used up a quota for this kind of call, such as the daily search quota. quotaResetAt or details says when it frees up.
429rate_limitedToo many requests: yours, or Kenso's to a service it calls for you.
500internal_errorThe request failed inside Kenso.
502provider_rejectedThe provider refused the workspace's API key.
503auth_unavailableKenso could not check the API key just now.
503crm_unavailableKenso cannot reach the CRM right now.
503provider_unavailableA service Kenso needs for this request is not set up, or did not answer.
503service_unavailableKenso cannot serve the request right now.
503social_data_unavailableSocial data could not be read right now.
503try_againAnother action on the same thing is still running, such as another call starting.
503voice_notes_unavailableVoice notes are not available right now, or the voice provider did not answer.
504upstream_timeoutA service Kenso called for this request took too long to answer.

More guides

On this page