# Error Codes

> Stable errors returned by MCP and CLI.

Canonical: https://keta1930.github.io/icml2026-mcp/en/docs/reference/errors



Failures use:

```text
error[code]: public short message
```

Keys, provider responses, query text, vectors, internal paths, and unknown exception details are not returned.

## Stable errors [#stable-errors]

| Code                         | Retry by default? | Meaning                                                                   |
| ---------------------------- | ----------------: | ------------------------------------------------------------------------- |
| `invalid_request`            |                No | Invalid parameter, length, range, or required value                       |
| `session_not_found`          |                No | Session is missing, expired, or closed                                    |
| `session_capacity_reached`   |             Later | Active-session limit reached                                              |
| `rate_limited`               |               Yes | Source or global rate/count limit reached                                 |
| `server_busy`                |               Yes | The service queue is full or timed out                                    |
| `embedding_unavailable`      |         Sometimes | DashScope is unavailable, misconfigured, or returned an unusable response |
| `embedding_quota_exhausted`  |                No | DashScope free quota or account balance exhausted                         |
| `index_unavailable`          |                No | Local index missing, damaged, or contract-mismatched                      |
| `index_build_limit_exceeded` |                No | Explicit index-build input limit reached                                  |
| `internal_error`             |                No | Unknown service error; details stay behind the safe log boundary          |

Back off for `rate_limited`, `server_busy`, or a temporary `embedding_unavailable`. Quota, index, configuration, and invalid-request errors require the stated condition to be fixed before retrying.