Troubleshooting

Every error carries a category or a machine-readable code you can match on.

Registering a target

create_target runs one live probe. On failure it returns a category and saves nothing, so fix what it names and call it again.

Category	What it means	Fix
`invalid_url`	`endpoint_url` names no endpoint we can call: a scheme other than `https://` or `wss://`, no host, an invalid port, or the session-id placeholder outside the URL path	Fix the URL as the message says
`unreachable`	DNS, connection, or timeout; the probe never got a reply	Check `endpoint_url` and that the endpoint is reachable from the public internet (private addresses are rejected)
`auth_failed`	The target answered but refused authentication	Over MCP: `create_target` asks for no key, so if the agent needs one, add it in the Enoki app (Inventory → Add integration). Over the REST API: check `auth_type` and `credential` match what the target expects. For `oauth_client_credentials`, the message names whether it was the mint that was rejected (wrong `client_id` / secret / scope) rather than your agent endpoint
`parse_error`	A reply arrived, but nothing was found at `response_field`	Fix the dot-path; the error names the path that matched nothing
`no_reply`	The text at `response_field` was the message we sent	Point `response_field` at the reply rather than the field holding your message. A target that stores the message and answers later in the conversation returns only your message from the POST
`not_an_endpoint`	The URL redirected or answered 404/405, so it serves no API for our request	A web page (a homepage or docs page) was pasted instead of the agent’s API. Use the URL your application posts chat messages to; the message names the redirect target or the methods the address does accept
`unknown`	An unexpected error while probing	Read the error detail, fix what it points to, and retry

Authentication errors

Status	Code	Meaning	Fix
401	`api_key_malformed`	No credential, or the `Authorization` header isn’t `Bearer <key>`	Over MCP, sign in from your client. Otherwise send `Authorization: Bearer egk_…`
401	`api_key_invalid`	The key is wrong, revoked, or rotated out past its grace window	Mint or rotate a key in Settings → API Keys (API keys & scopes)
401	`oauth_token_invalid`	The app’s connection has ended: it was disconnected or expired, or the person who approved it lost the right to	Connect the app again
403	`scope_denied`	The key or connection is valid but lacks the scope this tool needs	For a key, grant the scope and re-mint; see the scope → tool map. For a connected app, allow it under Settings → Connected apps, or connect the app again if it isn’t offered there and disconnect the old connection
503	`auth_unavailable`	A connected app’s access couldn’t be checked just now	Retry shortly

Signing in an app

When an app signs in, Enoki opens in your browser. If it can’t let the app in, the page says why:

The page says	What to do
Only a workspace owner or admin can connect an app	Ask an owner or admin for an API key with the scopes you need. You can still cancel the sign-in
Your account isn’t in an Enoki workspace yet	Workspaces are set up with our team: book a call from the page. If your team already uses Enoki, choose I have an invite code and paste the code or link a workspace admin sent you to join and carry on
A self-serve trial account can’t connect apps	A self-serve trial runs from its own dashboard and doesn’t include the MCP server. Book a call from the page to set up a full workspace
This sign-in has expired or was already answered	A sign-in waits ten minutes for an answer. Start it again from the app
Too many sign-ins from this network just now	Wait a minute, then start again from the app
This app is set up with the wrong address for Enoki	Set the server address in the app to exactly `https://mcp.enokilabs.ai/mcp`
Your browser is blocking storage for this site	Allow site storage for app.enokilabs.ai, then start again from the app
Something went wrong on our side	Start the sign-in again from the app
The app’s sign-in request couldn’t be accepted	Start again from the app. If it keeps failing, connect it with an API key

Rate limits (429)

Each API key and each connected app is rate-limited per minute. Every request counts against the Standard tier; the three expensive tools additionally count against the stricter Expensive tier.

Tier	Limit	Applies to
Standard	120 / min	every tool call
Expensive	10 / min	`create_target`, `trigger_assessment`, `validate_fix` (also counted against Standard)

On breach you get a 429 with code rate_limited. Because expensive tools spend both budgets, a burst of cheap calls can exhaust the Standard tier and 429 the next create_target.

Per-caller limits

Two further limits apply to every request, keyed on the calling IP address rather than on your key or app. They exist to stop path scanning, and normal integration traffic does not come close to either.

Limit	Window	Counts
Overall ceiling	1500 / min	every request from your IP, on any endpoint
Client errors	60 / min	only responses that were 403 or 404

The client-error bucket is the one to know about, because a full bucket refuses every request from that IP for the rest of the minute — not just the ones that were erroring. Two habits fill it:

Retrying a 404. A 404 means the resource is not there; a retry returns the same 404 and spends another entry. Do not retry them.
Polling for a resource before it exists. Poll the parent listing, or the run’s status, rather than the not-yet-created child.

Repeated 403 scope_denied counts too, so fix the scopes rather than looping on the failure. 429s from these two limits carry a Retry-After header and a plain detail message rather than a code field, so branch on the status and the header, not on a code, when handling them.

Daily assessment budget

Separately from the per-minute tiers above, each workspace has a budget of 20 assessment runs per rolling 24 hours. This one is not per API key and not per minute: it is shared across the dashboard, the external API, and MCP, because what it protects is the cost of running an assessment rather than request volume. Every run the workspace starts counts, whatever its outcome and whoever started it — including runs you did not trigger by hand, such as scheduled runs, safety assessments, and reporting top-ups started from the dashboard. So the budget can be spent before you have made 20 explicit trigger calls. The error message always reports the actual count, so read that number rather than assuming it matches your own triggers. The same budget refuses those creators too. A safety assessment or a reporting top-up started when the workspace has no slot left gets the same 429 with trigger_quota_exceeded and the same Retry-After; in the dashboard, all three lenses show the same “Daily assessment budget reached” notice. A reporting top-up is a run you start in Reporting when a risk needs more testing before its report can be downloaded. It tests those risks and re-tests the fixes you reported. On breach you get a 429 with code trigger_quota_exceeded — so a 429 from a trigger carries one of two codes, and they mean different things:

Code	Cause	What to do
`rate_limited`	Too many requests this minute	Back off and retry — usually seconds
`trigger_quota_exceeded`	The workspace’s 24-hour assessment budget is spent	Retry no earlier than the reset the error names, when enough runs have aged out of the window

How the reset reaches you depends on the surface. On REST, both codes carry a Retry-After header, and trigger_quota_exceeded additionally carries retryAfterSeconds in the response body. On MCP, neither does — tool errors are plain text with no headers — so trigger_assessment puts the reset time in the message itself. Treat that time as the earliest a slot can open, not a guarantee: runs started while you wait push it later. If you are hitting this from a release hook that triggers an assessment on every deploy, a scheduled re-run is the supported way to get a recurring cadence — talk to us and we will set it up rather than have you spend the budget on hook volume.

Assessment allowance (403)

Every workspace has a per-lens allowance, and a spent one returns 403. Which refusal you get depends on your plan, and the code in the body tells them apart.

Your monthly allowance is spent

A paid workspace gets a fixed number of runs per lens, per calendar month: security assessments, safety assessments and reporting top-ups are counted separately, so spending one does not reduce the others. The month is UTC and the counts reset on the 1st. Only completed runs count, in every lens. A run that ends in error, and one you cancel, costs no allowance and can be retried.

A cancelled run is not a passing run. get_assessment_status still returns a min_severity verdict once a run is terminal, and cancelled is terminal — so a run stopped early reads pass simply because it never got far enough to find anything. If you gate a pipeline on the verdict, compare categories_completed against categories_planned, or treat cancelled as its own outcome. The same applies to GET /api/v1/run/{run_id}.

When a lens’s allowance is spent, the trigger returns 403 with code assessment_allowance_spent, and the body names the count, the ceiling and the reset date:

{
  "detail": {
    "code": "assessment_allowance_spent",
    "message": "Assessment allowance reached: 10 of 10 security assessments used this month. Resets 1 Oct 2026. Contact Enoki to lift it.",
    "lens": "security",
    "used": 10,
    "limit": 10,
    "resets_at": "2026-10-01T00:00:00Z"
  }
}

This one does reset, on the date in resets_at — but it carries no Retry-After, because that can be most of a month away and is not a wait a client should sit through. Schedule around the date, or get in touch and we will raise the ceiling.

You are on an evaluation

Workspaces on an evaluation get a fixed number of security assessments for the life of the evaluation rather than per month. Safety assessments and reporting top-ups are not part of an evaluation and are refused outright, so there are two more refusals here. When the security allowance is spent, the trigger returns 403 with code trial_lens_limit_reached, and the body names the count and the ceiling:

{
  "detail": {
    "code": "trial_lens_limit_reached",
    "message": "Trial limit reached: 2 of 2 security assessments used. Contact Enoki to lift it.",
    "lens": "security",
    "used": 2,
    "limit": 2
  }
}

Asking for a safety assessment or a reporting top-up on an evaluation returns 403 with code trial_lens_not_included instead. That is not a spent allowance, so it carries no counts:

{
  "detail": {
    "code": "trial_lens_not_included",
    "message": "A trial workspace covers security assessments. Contact Enoki to add reporting top-ups.",
    "lens": "compliance"
  }
}

A reporting top-up’s lens value is compliance. Neither of the two evaluation refusals resets — do not retry them. Unlike the monthly allowance above and the two 429s, no amount of waiting frees a slot; we lift the ceiling or add the lens, so get in touch. A run that ends in error does release its slot, so a run that fails on our side does not cost you an assessment. All three refusals share one body shape, so branch on code and read the counts where they apply. The examples above show only the fields each refusal fills in; the rest are present and null — resets_at on both evaluation refusals, and used and limit on trial_lens_not_included, which short-circuits before anything is counted. One more refusal applies to an evaluation only. It runs full assessments, so a trigger that passes categories returns 403 with code trial_focus_not_included. Unlike the two above, you clear this one yourself: leave categories out and trigger again. Its body carries the code and the message and nothing else:

{
  "detail": {
    "code": "trial_focus_not_included",
    "message": "A trial workspace runs full security assessments. Leave out the categories, or contact Enoki to focus a run on chosen ones."
  }
}

On MCP these refusals arrive as a trigger_assessment tool error carrying the message and nothing else — an MCP tool error has no body, so there is no code to branch on there. Use the REST trigger if your client needs to tell them apart. Listing the categories (GET /api/v1/category, or the list_categories MCP tool) is part of the platform plan. A trial workspace is refused it:

{
  "detail": {
    "code": "taxonomy_not_included",
    "message": "Listing the test categories is part of the Enoki platform plan, not a trial. Contact Enoki to upgrade."
  }
}

Like the evaluation refusals above, it does not reset with time. A trial’s runs cover every category, so omit categories when you trigger one.

A run that could not start (502)

If Enoki accepts a trigger but cannot start the run, the trigger returns 502:

{
  "detail": {
    "code": "run_not_started",
    "message": "The run could not be started. Try again in a minute."
  }
}

The run is recorded as failed and does not count against your assessment allowance, so trigger again. It does count as a start toward the daily assessment budget. Over MCP, trigger_assessment returns a tool error saying the run could not be started.

”Not found” for something you expect to exist

A finding, run, or target in a different workspace returns not-found, not 403, so IDs can’t be probed across workspaces. If you get not-found for an ID you believe is valid, check your key or app is connected to the right workspace.

Can’t connect at all

Endpoint: confirm the URL is exactly https://mcp.enokilabs.ai/mcp (streamable HTTP).
Auth header: the key goes in the Authorization: Bearer … header, not a query parameter.
Signing in: if your client never opens Enoki in your browser, it can’t sign in to Enoki; connect it with an API key.
Client support: for a client without native remote-MCP support, use the mcp-remote bridge (see Connect your agent).

Get started

Connect

Integrations

MCP

REST API

Registering a target

Authentication errors

Signing in an app

Rate limits (429)

Per-caller limits

Daily assessment budget

Assessment allowance (403)

Your monthly allowance is spent

You are on an evaluation

A run that could not start (502)

”Not found” for something you expect to exist

Can’t connect at all

​Registering a target

​Authentication errors

​Signing in an app

​Rate limits (429)

​Per-caller limits

​Daily assessment budget

​Assessment allowance (403)

​Your monthly allowance is spent

​You are on an evaluation

​Category list (403)

​A run that could not start (502)

​”Not found” for something you expect to exist

​Can’t connect at all

Registering a target

Authentication errors

Signing in an app

Rate limits (429)

Per-caller limits

Daily assessment budget

Assessment allowance (403)

Your monthly allowance is spent

You are on an evaluation

Category list (403)

A run that could not start (502)

”Not found” for something you expect to exist

Can’t connect at all