# 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](https://frames.ag/docs/mcp.md) 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](https://frames.ag/settings/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](https://t.me/framesag). Include the `request_id` from the error if you have one.