> ## Documentation Index
> Fetch the complete documentation index at: https://docs.enokilabs.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Error categories, auth failures, and rate limits — what they mean and what to do.

Every error Enoki returns is categorized and actionable. Here are the ones
you'll actually hit, what each means, and how to fix it.

## Registering a target

`create_target` fires one live probe and, on failure, returns a category so you
know what to change. Nothing is persisted on a failed probe — fix and call it
again.

| Category      | What it means                                              | Fix                                                                                                                         |
| ------------- | ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `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/internal addresses are rejected) |
| `auth_failed` | The target answered but refused authentication             | Check `auth_type` and `credential` — they must match what the target expects                                                |
| `parse_error` | A reply arrived, but nothing was found at `response_field` | Fix the dot-path — the error names the path that matched nothing; check it against the target's actual reply shape          |

## Authentication errors

Each error carries a machine-readable `code` you can match on:

| Status  | Code                | Meaning                                                         | Fix                                                                              |
| ------- | ------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------- |
| **401** | `api_key_malformed` | The `Authorization` header isn't `Bearer <key>`                 | Send `Authorization: Bearer egk_…` — check your client's header config           |
| **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](/api-keys)) |
| **403** | `scope_denied`      | The key is valid but lacks the scope this tool needs            | Grant the scope and re-mint — see the [scope → tool map](/api-keys)              |

<Warning>
  The most common 403: **`write` does not imply `read`.** A write-only key can
  create a target but can't `list_targets` or `get_setup_guide`. The MCP setup
  flow needs a key with **both `read` and `write`** (and `test:run` to trigger
  runs). See [API keys & scopes](/api-keys).
</Warning>

## Rate limits (429)

Each API key is rate-limited per minute, in two tiers:

| Tier      | Limit     | Tools                                                                                                                                                     |
| --------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Standard  | 120 / min | the read and light-write tools — `list_targets`, `get_setup_guide`, `list_findings`, `get_finding`, `list_runs`, `get_assessment_status`, `close_finding` |
| Expensive | 10 / min  | the tools that launch outbound, token-spending work — `create_target`, `trigger_assessment`, `validate_fix`                                               |

On breach you get a **429** with code `rate_limited`: `Rate limit exceeded for MCP <tier> tools (<limit>). Slow down and retry.` The two tiers are independent — exhausting the expensive budget doesn't touch the standard one. Back off and retry.

## "Not found" for something you expect to exist

Requests for a finding, run, or target that belongs to a **different workspace**
return a **not-found** error, not a 403 — deliberately, so the error can't be
used to probe whether an ID exists in another workspace. If you get "not found"
for an ID you believe is valid, confirm your API key is for the **right
workspace**.

## Can't connect at all

If your MCP client won't connect:

* **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.
* **Client support** — for a client without native remote-MCP support, use the `mcp-remote` bridge (see [Connect your agent](/connect-your-agent)).
* **Transient `at_capacity` (503)** — if the server is momentarily at its concurrent-session cap, a new connection is refused with code `at_capacity`; retry shortly.