Troubleshooting

Connection errors

These come back before any tool runs.

Error	Cause	Fix
401 An API key is required…	The request has no key.	Check that the header is exactly Authorization: Bearer <key> and that the key was pasted whole. In Claude Desktop, check the env block in the setup.
401 Invalid API key.	The key is wrong or mistyped.	Create a new key and replace it.
401 This API key has been revoked. / has expired.	The key was revoked (by you, by the owner, or by Sign out other devices) or reached its expiry date.	Create a new key.
401 This API key’s account is no longer active.	The member behind the key was removed from the workspace.	Ask your workspace owner.
403 External AI apps are turned off for this workspace.	The owner switch is off.	Ask the owner to turn it on in Settings → AI apps (MCP). Your existing keys start working again.
403 External AI apps are available on paid plans.	The workspace is on the free plan.	Choose a paid plan.
402 does not have an active subscription / trial has ended / payment could not be processed / subscription is paused / has ended	A billing problem with the workspace.	The owner fixes billing in the web app.
413 The request body is too large.	A file upload over the limit.	Upload files up to 10 MB. Split larger documents.
429 Too many requests for this API key.	More than 120 calls in a minute.	Wait a minute.

Tool errors

These come back from a single tool call. Claude usually explains them and suggests the next step.

Code	What it means
read_only_key	The key is read-only. Use a full-access key to change data or start paid runs.
already_running	You already have a run of this kind going. The error includes its operation_id, so Claude can check that run instead.
rate_limited	More than 30 changes in a minute. Wait a minute, then continue.
QUOTA_EXCEEDED	The workspace’s AI budget for this period is used up.
not_found	No item with that id in your workspace. An id from another workspace or another person’s private item reads as not found.
forbidden	Your role does not allow it, for example deciding on a colleague’s discovery run.
needs_icp	Discovery needs a more complete ICP. Run kodlo_discovery_prepare and answer its questions.
contact_suppressed	The contact is marked Do Not Contact. AI apps cannot change it.
not_enough_identity	Lookup and enrichment need a LinkedIn URL, or a first name, last name and company.
unavailable	The capability is not available for your workspace. kodlo_whoami says why.
too_large	The document or file is over its size limit.
fetch_failed	kōdlo could not fetch the URL you asked to import. Check that it is public.
internal_error	Something went wrong on kōdlo’s side and the action did not complete. Try again. If it keeps failing, contact support.

Background runs that end without a result

Operation error	What it means
interrupted	A kōdlo update or restart stopped the run. Start it again.
not_started, busy, not_queued	kōdlo was too busy to start it. Nothing was spent. Try again.
timed_out	The run took too long. Try a narrower focus or a lighter research depth.
billing_unavailable	kōdlo could not check the workspace budget, so the run did not start.
canceled	The run was cancelled. Work done before cancelling was billed.

Claude does not see the kōdlo tools

• Claude Code: run claude mcp list. If kodlo is missing, add it again with the command in Setup.
• Claude Desktop: make sure the config file is valid JSON and Node.js is installed (node -v), then fully quit and reopen the app.
• Ask Claude “What can you do in my kōdlo workspace?”. If kodlo_whoami runs, the connection works.

Still stuck? Email support@kodlo.ai with the error text.