Errors

Every error from the K-Agent API has the same shape, a stable code you can branch on, and a message written for people in Arabic or English.

The error envelope

{
  "error": {
    "type": "conflict_error",
    "code": "session_busy",
    "message": "This session is answering another message. Retry in a moment.",
    "request_id": "req_01k6rz9f1j3m5p7r9t1w3y5a7c",
    "doc_url": "https://k-agent.kerneltics.com/docs/en/reference/errors/#session_busy"
  }
}

Field	Description
type	The broad category, below.
code	Stable, snake_case. Branch on this. New codes may be added; treat unknown ones by their type and HTTP status.
message	For people, in the language of Accept-Language (ar or en). It can change at any time — never parse it.
param	Present when one parameter is at fault: a field name, or a JSON pointer such as /tools/max_tool_rounds.
request_id	The same value as the Request-Id response header. Quote it when you contact support.
doc_url	A link to this page, at the code’s row.

Types and statuses

type	HTTP status	Meaning
invalid_request_error	400 (malformed), 422 (understood but invalid), plus 405, 413 and 428	Fix the request.
authentication_error	401	The credential is missing, invalid, expired or revoked.
permission_error	403	The credential is valid but may not do this.
not_found_error	404	It doesn’t exist — or it belongs to another project or another end user.
conflict_error	409, or 412 for a stale If-Match	The current state doesn’t allow it.
rate_limit_error	429	Too many requests; wait for Retry-After.
quota_error	429	A plan or cost limit was reached.
provider_error	502	The AI provider failed.
api_error	500, 503	Something went wrong on our side.

Retrying safely

• Retry 429 after the Retry-After seconds, 409 session_busy, session_queue_full and idempotency_in_progress after a short pause, and 500, 502 and 503 with exponential backoff. Codes marked Retryable below are the ones worth retrying.
• Don’t retry when the response has x-should-retry: false (for example quota_exceeded), or for other 4xx errors — fix the request first.
• Always send an Idempotency-Key on POST requests you might retry, so a retry can never create a second message, session or ticket. See Idempotency.

Errors in streams

Errors that happen before a stream starts are normal JSON responses. After it starts, a failed run ends with a run.failed event that carries run.error, and the error event is used only for stream faults (token_expired, stream_timeout, internal_error). See Runs and streaming.

Error codes

Invalid request (400, 405, 413, 422, 428)

Code	Meaning · What to do
allowed_origins_required HTTP 422	A publishable key needs at least one allowed origin, such as https://www.example.com. What to do: Add at least one origin (scheme://host[:port]) to the publishable key's allowed_origins.
credential_invalid HTTP 422	The AI provider rejected this API key. Check the key and try again. What to do: The provider rejected the key during the live check. Copy the key again from the provider's console and make sure it can call the chosen model.
draft_not_allowed HTTP 422	The draft can only run in playground sessions. What to do: version: "draft" runs only in playground sessions (channel: "playground"), for editors or keys with agents:write. Publish to use the changes anywhere else.
external_id_invalid HTTP 422	The external_id format is invalid. Use 1 to 128 Latin letters, digits or the characters . _ : -, starting with a letter or digit. Session IDs must not start with sess_ and end-user IDs must not start with eu_. What to do: Use 1–128 characters from A–Z a–z 0–9 . _ : -, starting with a letter or digit. Session IDs must not start with sess_, end-user IDs must not start with eu_.
idempotency_key_reused HTTP 422	This Idempotency-Key was already used with a different request. Use a new key for each new request. What to do: Use a new Idempotency-Key for each distinct request. Reuse a key only to retry the exact same request.
identity_as_parameter HTTP 422	Tools that require a verified customer must not ask the model for identity details such as phone numbers or emails. Use end_user placeholders instead. What to do: Remove phone, email or user-ID parameters from tools that need a verified user, and use {{end_user.external_id}} or {{end_user.traits.*}} placeholders instead.
if_match_required HTTP 428	This change needs an If-Match header with the current etag. What to do: Send If-Match: <etag> with the draft's current etag when you PATCH the agent configuration.
input_too_large HTTP 413	The input is too long. What to do: Shorten the input: up to 4,000 characters with browser credentials, 32,000 with a secret key.
invalid_api_version HTTP 400	The K-Agent-Version header names an unknown API version. What to do: Send K-Agent-Version: 2026-10-06, or leave the header out.
invalid_cursor HTTP 400	The pagination cursor is not valid for this list. What to do: Use first_id or last_id from a previous page of the same list, and don't send after and before together.
invalid_idempotency_key HTTP 400	The Idempotency-Key header must be 1 to 255 characters long. What to do: Keep Idempotency-Key between 1 and 255 characters; a UUID works well.
invalid_json HTTP 400	The request body is not valid JSON. What to do: Send a valid JSON body. Check quotes and trailing commas.
invalid_parameter HTTP 400	The parameter "{param}" has an invalid value. What to do: Fix the value named in param; the API reference lists the allowed values.
method_not_allowed HTTP 405	This endpoint doesn't support this HTTP method. What to do: Use the HTTP method the API reference shows for this path.
model_not_allowed_on_plan HTTP 422	This model isn't available on your current plan. What to do: Pick a model your plan allows (GET /v1/models shows allowed_on_plan) or upgrade the plan.
override_not_allowed HTTP 422	This agent doesn't allow changing this setting per request. What to do: Add the field to the agent's overrides.allowed (and the model to overrides.models), publish, then retry. never_handle, escalation_reply and tool grants can never be overridden.
placeholder_unresolved HTTP 422	A placeholder in the tool's URL, headers or body had no value, so the call was not made. What to do: A {{…}} placeholder in the tool's URL, headers or body had no value, so nothing was sent. Make the parameter required, pass the variable, or check the end user's traits.
project_mismatch HTTP 400	The X-Project-Id header names a different project from the one this key or token belongs to. What to do: API keys and tokens already belong to a project. Drop the X-Project-Id header, or use a key from that project.
project_required HTTP 400	Choose a project by sending its ID in the X-Project-Id header. What to do: Dashboard cookie requests must send X-Project-Id. With an API key, the project comes from the key.
reference_not_found HTTP 422	The configuration refers to an item that doesn't exist in this project. What to do: The configuration points at an ID (tool_…, ks_…, pcred_…) that doesn't exist in this project. Create the item first or fix the reference.
request_too_large HTTP 413	The request body is too large. What to do: Keep request bodies under 1 MiB (5 MiB for knowledge sources).
secret_host_not_allowed HTTP 422	A secret can only be sent to the hosts listed in its allowed_hosts. What to do: Add the tool's host to the secret's allowed_hosts, or use a separate secret for that host.
secret_variable_not_persistable HTTP 422	Secret variables can only be sent with a single message or ask request; they are never stored on a session. What to do: Send secret variables with each request (ask or messages), never on POST /v1/sessions or PATCH.
system_message_not_allowed HTTP 400	System and developer messages aren't accepted; the agent's own instructions apply. What to do: Remove system and developer messages and put instructions in the agent. If the agent allows the instructions_append override, they are used as per-request instructions.
tool_name_conflict HTTP 422	Another tool of this agent already uses this name. What to do: Rename the tool: names must be unique across the agent's built-in, HTTP and client tools.
tool_not_declared HTTP 400	The request includes a tool that the agent doesn't declare as a client-side tool. What to do: Only send tools that the agent declares as client tools, with the same names.
tool_outputs_incomplete HTTP 422	Send an output for every pending tool call. What to do: Send one output for every call_id in required_action.tool_calls.
tools_not_allowed_with_session HTTP 400	Client-side tools can't be sent when the request is bound to a session. What to do: Drop tools from OpenAI-compatible requests bound to a session, or call without a session.
unknown_event_type HTTP 422	The event list contains a type that is not in the event catalog. Use catalog event types or ["*"]. What to do: Subscribe only to event types from the catalog in the webhooks guide, or to ["*"] for all of them.
unknown_field HTTP 400	The field "{param}" is not recognized. What to do: Remove the field named in param. Unknown fields are rejected so that typos never pass silently.
unknown_model HTTP 422	This model is not known. What to do: Use a model ID from GET /v1/models.
unsupported_content_type HTTP 422	Only text content is supported. What to do: Send text only: input as a string or as [{"type":"text","text":"…"}].
unsupported_parameter HTTP 400	The request uses a parameter that isn't supported. What to do: Remove n greater than 1, logprobs or response_format: json_schema from OpenAI-compatible requests.
url_not_allowed HTTP 422	This URL is not allowed. Use a public https:// address. What to do: Use a public https:// URL on port 443 or 8443. Private, loopback and cloud-metadata addresses are blocked.
validation_failed HTTP 422	The request contains an invalid value. What to do: Fix the value at the JSON pointer in param; the message says what is wrong.
variable_missing HTTP 422	A required variable was not provided. What to do: Send every variable the agent marks required.
variable_unknown HTTP 422	The request sets a variable that this agent doesn't declare. What to do: Send only variables the agent declares, and check their spelling.
webhook_endpoint_limit_reached HTTP 422	This project already has the maximum number of webhook endpoints. What to do: A project can have up to 10 webhook endpoints. Delete one, or subscribe an existing endpoint to more events.

Authentication (401)

Code	Meaning · What to do
authentication_required HTTP 401	Authentication is required. Send your API key in the Authorization header as "Bearer <key>". What to do: Send Authorization: Bearer <key> with a secret key, a publishable key or a client token.
invalid_api_key HTTP 401	The API key is invalid, expired or revoked. What to do: The key is mistyped, expired, rolled or revoked. Create or roll a key in the dashboard.
invalid_client_token HTTP 401	The client token is invalid. What to do: Mint a new client token on your server with POST /v1/client_tokens.
invalid_credentials HTTP 401	The email or password is incorrect. What to do: Check the email and password. Repeated failures are rate limited.
token_expired HTTP 401	The client token has expired. Request a new one. What to do: Get a new client token (widget: POST /v1/widget/token/refresh; your server: POST /v1/client_tokens) and reconnect streams with Last-Event-ID. Open streams receive this code as an error event.

Permission (403)

Code	Meaning · What to do
csrf_check_failed HTTP 403	This request was blocked because it came from another site. What to do: Dashboard cookie requests must be same-origin JSON requests. Server integrations should use an API key, not cookies.
insufficient_scope HTTP 403	This API key doesn't have the scopes this request needs. What to do: Use a key that has the scope this route needs (for example runs:write or sessions:read), or a key with permissions: "all".
origin_not_allowed HTTP 403	This website's origin is not allowed for this key. Add it to the key's allowed origins. What to do: Add this exact origin (scheme://host[:port]) to the publishable key's allowed_origins.
origin_required HTTP 403	Requests with a publishable key must come from a browser that sends an Origin header. What to do: Publishable keys only work from browsers, which send Origin. From a server, use a secret key.
permission_denied HTTP 403	You don't have permission to do this. Required permission: {permission}. What to do: Your role lacks the permission named in the message. Ask an admin for a role that includes it.
principal_not_allowed HTTP 403	This kind of credential can't call this endpoint. What to do: This route needs a secret key or a dashboard user. Publishable keys and client tokens can call only the browser routes listed under End users & identity.
signup_closed HTTP 403	Sign-up is closed on this server. Ask an administrator for an invitation. What to do: Ask an administrator for an invitation.

Not found (404)

Code	Meaning · What to do
project_not_found HTTP 404	Project not found, or you are not a member of it. Check the X-Project-Id header. What to do: Check the X-Project-Id header: the project doesn't exist, or you aren't a member of its organization.
resource_not_found HTTP 404	The requested {resource} was not found. What to do: Check the ID or slug. Items in another project, or owned by another end user, also return 404.
route_not_found HTTP 404	There is no endpoint at this path. Check the URL against the API reference. What to do: Check the path, including the /v1 prefix, against the API reference.
session_not_found HTTP 404	Session not found. Create sessions with POST /v1/sessions; you can then use either its ID or your external_id. What to do: Create sessions with POST /v1/sessions (get-or-create), then address them by sess_… ID or by your external_id.

Conflict (409, 412)

Code	Meaning · What to do
agent_archived HTTP 409	This agent is archived and no longer answers new messages. What to do: The agent was archived (DELETE /v1/agents/{agent}). Use another agent, or create a new one from its export.
agent_not_ready HTTP 409	The agent isn't ready to answer yet. Check the blockers listed in its readiness. What to do: Read the agent's readiness.blockers (GET /v1/agents/{agent}): connect a provider key, pick a model your plan allows or turn off ai_paused. Retrying won't help until a blocker is fixed.
already_member HTTP 409	This person is already a member of the organization. What to do: The person is already in the organization; change their role instead.
client_message_id_conflict HTTP 409	This client_message_id was already used for a different message. What to do: You reused a client_message_id with different content. Generate a new ID for every new message; reuse an ID only to retry the same message.
email_taken HTTP 409	An account with this email already exists. Log in instead. What to do: Log in instead, or sign up with another email.
etag_mismatch HTTP 412	This item changed since you loaded it. Reload it and apply your changes again. What to do: The draft changed after you read it. Fetch the agent again, re-apply your change and send the new etag in If-Match.
handoff_already_assigned HTTP 409	Another team member has already claimed this handoff. What to do: Another teammate claimed it first. Refresh the queue; admins can reassign with force: true.
handoff_already_open HTTP 409	A handoff is already open for this session. What to do: This session already has an open handoff. Work it in the Handoff Desk, or resolve it before requesting another.
handoff_not_open HTTP 409	This handoff is no longer open. What to do: The handoff was already resolved or expired. Refresh it before acting.
idempotency_in_progress HTTP 409 Retryable	A request with this Idempotency-Key is still being processed. Retry after it finishes. What to do: The first request with this key is still running. Retry with backoff; once it finishes you get its stored result.
invitation_expired HTTP 409	This invitation has expired or was revoked. Ask for a new one. What to do: Ask an admin for a new invitation link. Links work once and expire after 7 days.
last_owner HTTP 409	An organization must keep at least one owner. What to do: Make another member an owner before removing or demoting this one.
model_not_configured HTTP 409	No API key is configured for this model's provider. Add a provider key in Settings. What to do: Connect a key for the model's provider (Settings → Model providers, or POST /v1/provider_credentials), or pick a model the platform provides.
name_taken HTTP 409	This name is already in use. Choose a different one. What to do: Pick a different name or slug.
no_open_handoff HTTP 409	This session has no open handoff. What to do: There is no open handoff to release or resolve. Fetch the session to check its mode.
run_already_completed HTTP 409	This run has already finished and can't be cancelled. What to do: The run already finished. Nothing to do.
run_not_requires_action HTTP 409	This run isn't waiting for tool outputs. What to do: Submit tool outputs only while the run's status is requires_action. Fetch the run to see its state.
session_agent_mismatch HTTP 409	This external_id already belongs to a session with a different agent. What to do: This external_id already belongs to a session with another agent. Use one ID per agent, for example by prefixing the agent slug.
session_busy HTTP 409 Retryable	This session is answering another message. Retry in a moment. What to do: The session is answering another message and uses concurrency: "reject". Wait Retry-After seconds, or switch the session to queue.
session_closed HTTP 409	This session is closed. What to do: You sent if_closed: "error". Leave it at the default reopen to reopen the session, or start a new one.
session_end_user_mismatch HTTP 409	This session belongs to a different end user. What to do: The session belongs to another end user, and a session's end user never changes. Use a different session ID.
session_exists HTTP 409	A session with this external_id already exists. What to do: You sent if_exists: "error" and the session exists. Drop the flag to resume it, or use a new external_id.
session_queue_full HTTP 409 Retryable	Too many messages are waiting in this session. Wait for the agent to reply, then try again. What to do: Ten messages are already waiting in this session. Wait for replies before sending more.
slug_taken HTTP 409	Another agent in this project already uses this slug. What to do: Another agent in this project uses this slug. Choose a different slug.

Rate limits and quota (429)

Code	Meaning · What to do
anonymous_limit_reached HTTP 429 Retryable	Too many messages right now. Please try again later. What to do: An anonymous widget visitor hit a per-IP, per-session or daily cap. Ask them to try later, or identify signed-in users with client tokens.
cost_cap_exceeded HTTP 429	The daily usage cap has been reached. Please try again tomorrow. What to do: The organization reached its daily model-cost cap. Sessions hand off and ask returns 429 until the next day; contact us to raise the cap.
playground_limit_reached HTTP 429	The daily limit for test conversations has been reached. Connect your own provider key to keep testing. What to do: Test-panel runs on platform models are capped per project per day. Connect your own provider key to keep testing, or try tomorrow.
quota_exceeded HTTP 429	Your plan's AI conversation quota for this month is used up. What to do: The plan's AI conversations for this month are used up (Free, or a paid plan with a hard cap). Upgrade or wait for next month; the response carries x-should-retry: false.
rate_limited HTTP 429 Retryable	Too many requests. Wait a moment and try again. What to do: Wait the number of seconds in Retry-After, then retry, and spread requests out.

AI provider (502)

Code	Meaning · What to do
provider_auth_failed HTTP 502	The AI provider rejected the credentials. What to do: The model provider rejected the credentials. Check or replace the provider key.
provider_bad_request HTTP 502	The AI provider rejected the request. What to do: The provider rejected the request. Check the model settings; contact support with the request_id if it persists.
provider_error HTTP 502 Retryable	The AI provider returned an error. What to do: Retry later. Configure model.fallback_models so runs continue on another model.
provider_overloaded HTTP 502 Retryable	The AI provider is overloaded. Try again shortly. What to do: Retry with backoff; model.fallback_models keeps conversations going meanwhile.
provider_rate_limited HTTP 502 Retryable	The AI provider is limiting requests. Try again shortly. What to do: The provider is rate limiting the key. Retry with backoff or raise your limits with the provider.
provider_refusal HTTP 502	The AI model declined to answer. What to do: The model declined to answer. K-Agent tries fallback_models, then sends the fallback message and hands sessions to staff.
provider_timeout HTTP 502 Retryable	The AI provider took too long to respond. What to do: Retry. If it keeps happening, choose a faster model or a smaller max_reply_tokens.
provider_unavailable HTTP 502 Retryable	The AI provider is unavailable right now. What to do: Retry later, and configure model.fallback_models.

Server (500, 503)

Code	Meaning · What to do
internal_error HTTP 500 Retryable	Something went wrong on our side. Please try again; if it keeps happening, contact support with the request ID. What to do: Retry with backoff. If it keeps happening, contact support with the request_id.
service_unavailable HTTP 503 Retryable	The service is temporarily unavailable. Try again shortly. What to do: The server is restarting or overloaded. Retry with backoff.

Codes outside HTTP responses

These codes never come back as an HTTP error. They appear in a run’s error (run errors), as a stream error event, or in a tool result that only the model sees — you will find them in run steps and the dashboard’s Debug tab.

Code	Meaning · What to do
handed_off Tool result	The conversation was handed to a member of staff. What to do: Returned to the model for the remaining tool calls of a round in which a liability handoff ended the turn. Nothing to do.
no_model_credential Run error	No API key is connected for the agent's AI provider. What to do: The agent's AI provider has no API key, so the run ended with the fallback message. Connect a provider key (Settings → Model providers, or POST /v1/provider_credentials). API calls get 409 agent_not_ready with this blocker instead.
run_interrupted Run error Retryable	The run was interrupted before it finished. What to do: The run stopped before finishing (for example during a server restart) and ended through the never-silent path. Check the session and send the message again if needed.
stream_timeout Stream event Retryable	The stream was open too long and has been closed. Reconnect with Last-Event-ID to continue. What to do: Reconnect with Last-Event-ID (or ?after=) to continue from the last event you received.
ticket_already_open Tool result	This customer already has an open ticket. What to do: Returned to the model when the customer already has an open ticket; it tells them the existing ticket number. Nothing to do.
too_many_calls Tool result	Too many tool calls in one step. What to do: At most 5 tool calls run per round; the model receives this for the extra calls. Nothing to do.
tool_outputs_expired Run error	The run waited too long for tool outputs and was stopped. What to do: Tool outputs must arrive within 10 minutes of requires_action. The run is failed; send a new message to continue.
unreadable Tool result	The lookup came back in a form that could not be read. What to do: Your HTTP tool's endpoint returned something that isn't JSON or doesn't match response.items_path and fields. Fix the endpoint or the projection, and check it with POST /v1/tools/{tool}/test.
upstream_failed Tool result Retryable	The lookup could not be completed right now. What to do: Your HTTP tool's endpoint failed (non-2xx, timeout, over 1 MiB or a blocked address). Inspect the run steps and test the tool.

Warnings

Some successful responses carry warnings: non-fatal notes worth logging.

Warning	Meaning
external_id_looks_like_phone	The external_id looks like a phone number. Keep personal data out of IDs; store contact details in end-user traits.
external_id_looks_like_email	The external_id looks like an email address. Same advice.
create_params_ignored	The session already existed, so creation-only settings in the request were ignored.
client_history_ignored	OpenAI-compatible endpoint: the session’s stored history was used and earlier messages in the request were ignored.
identity_as_parameter	A tool parameter is named like personal identity data. Turn on requires_verified_user and use end_user placeholders instead.