Reference
Troubleshooting
Fixes for common connection problems and API errors.
Most problems come from an app's connection settings or from an API key. Find yours below.
Connecting#
| Problem | Fix |
|---|---|
| Your AI never uses Frames | Ask it to use Frames by name. In Claude, turn Frames on in the chat under + → Connectors. |
| Claude won't let you add a connector | Free plans allow one custom connector, so remove another one first. On Team or Enterprise, ask an owner to add Frames. |
| ChatGPT has no way to add a plugin by URL | Turn on Developer mode first. It's available on paid plans, on the web. |
| Cursor's install link does nothing | Update Cursor to 3.15.12 or later, or add Frames to ~/.cursor/mcp.json by hand. |
| VS Code shows the Frames tools as disabled | You declined to trust the server. Run MCP: Reset Trust. On Copilot Business or Enterprise, ask an admin to allow MCP servers. |
| Sign-in keeps failing or asking again | Remove the connection and add it again. In Claude Code, use Clear authentication under /mcp. In OpenCode, run opencode mcp logout frames, then opencode mcp auth frames. |
| An agent using an API key gets "unauthorized" | Send the key as Authorization: Bearer <your key>, and check that it hasn't been revoked. |
| Your app only runs local MCP servers | Bridge with npx mcp-remote https://api.frames.ag/mcp. |
The Connect with MCP page has the full setup for each app.
Errors#
API errors come back as { "error": { "type", "message", "code", "request_id" } }. MCP tools report the same problems as tool errors.
| Error | What it means | What to do |
|---|---|---|
| Unauthorized (401) | The API key is missing, wrong or revoked | Send Authorization: Bearer <your key>, or create a new key |
insufficient_credits (402) | Your balance is below this request's budget | Set a lower budget with budget_usd or max_usd, wait for your monthly credits, or upgrade |
requires_approval (402) | The budget is over your project's policy, so the run is paused and holds no credits | Approve it with a max_usd, or cancel it |
no_subscription (403) | The project has no active plan | Check your plan under Settings → Plans & Billing |
probe_rate_limited | This hour's free probes are used up | Wait under an hour. Search hits marked invoke_ready don't need a probe. |
not_found | The run or tool id isn't in your project | Check the id; each run is only visible to its own project |
search_failed | The catalog was briefly unavailable | Retry once |
| Rate limited (429) | Too many requests in a short time | Slow down and retry |
Still stuck?#
Ask us on Telegram. Include the request_id from the error if you have one.