Troubleshooting
Every error code the API returns, what it means and how to fix it.
Errors from the API use the OpenAI envelope: {"error": {"message", "type", "code"}}. This page lists the codes you may see and what to do about them.
| Code | HTTP | Meaning | Fix |
|---|---|---|---|
invalid_api_key | 401 | Missing, malformed, revoked or expired key or token | Send Authorization: Bearer sk-memtro-…. Create a key on Dashboard → API keys. Older sk-brain- keys still work. |
provider_not_configured | 400 | No key for the provider the model needs | Add one under Dashboard → Providers. claude-code/* needs a Claude Code token or Anthropic key under the Claude Code provider. |
model_not_found | 404 | Unknown model id | Use auto, memtro, provider/model, claude-code/<alias> or compat:<label>/<model>. GET /v1/models lists what you can use. |
routing_unavailable | 400 | auto could not find a usable ladder | Add a provider key or set a ladder under Dashboard → Routing. |
unsupported_tools | 400 | Client-declared tools with a claude-code/* model | Use an anthropic/* model with an API key for client tools, or drop the tools array. |
engine_unavailable | 503 | The Claude Code engine is not available right now | Retry, or use an anthropic/* model; contact support if it persists. |
upstream_error | provider's | The model provider returned an error | The message carries the provider's text: invalid key, rate limit, overloaded model. |
invalid_request_error | 400 | The body failed validation | The message names the field. |
Symptoms rather than codes
"invalid x-api-key" from Anthropic. You pasted a Claude Code token (sk-ant-oat01-…) under the Anthropic provider. Tokens belong under the Claude Code provider; Anthropic takes Console keys (sk-ant-api03-…).
No memory in answers. Retrieval needs embeddings, which come from an OpenAI or Google key. Add one under Providers even if you chat through Anthropic or Claude Code.
No connector tools. Tools appear only for systems you (or your organisation) have connected on Dashboard → Connections. Personal connections serve only your requests.
The agent did not check a system. Say which systems to use in the question, or run in agent mode (auto:agent), which cross-references by default. The answer ends with a line per system consulted.
A job did not run. Check it is enabled and that the next run time has passed; jobs are checked every minute. The job's panel on Dashboard → Jobs shows the last error.
Requests time out in my client. Agent runs can take minutes. Raise the client timeout; stream responses to see progress as reasoning_content.
Memtro falls back to the native engine. The response carries memtro.engine_note with the reason, usually that the OpenCode or Claude Code runner is not available on the server, or that client tools were declared.