Errors
The error shapes on each layer, the codes that matter, and what an agent should do with each.
There are three layers a request can fail on, and each has one shape.
Inside a tool call
A tool that fails returns an MCP tool result marked isError, never a dropped connection or a protocol error. The text carries the code, the message, and where possible an actionable hint, so the agent can tell the user what to do rather than retrying.
| Code | Meaning | What to do |
|---|---|---|
INSUFFICIENT_CREDITS | The workspace is out of credits. | Stop paid calls. Free tools keep working. Top up or wait for renewal. |
PLAN_UPGRADE_REQUIRED | The feature needs a higher plan; the message names it. | Do not retry. Tell the user which plan unblocks it. |
PLAN_LIMIT_REACHED | A count limit was hit (projects, trackers). The message states the limit. | Archive or delete something, or upgrade. |
VALIDATION_ERROR | An argument was missing or out of range. | Fix the arguments; the message says which. |
NOT_CONNECTED | The project has no Search Console, Analytics, or PostHog connection. | Connect it in the dashboard. |
RECONNECT_REQUIRED | A connection exists but its access has lapsed or been revoked. | Reconnect in the dashboard. |
PROVIDER_BILLING_ISSUE | The upstream data provider refused the call. | Not something the user can fix; contact support if it persists. |
Not-found conditions use plain messages: Project <id> not found in this workspace. (the same whether the id is unknown or belongs to someone else), Tracker <id> not found., No audits found for this project.
In front of the endpoint
Authentication failures at the credential layer use the RFC 6749 shape:
{ "error": "invalid_api_key", "error_description": "The provided API key is invalid, expired, or disabled" }| Status | error | Meaning |
|---|---|---|
| 401 | invalid_api_key | Unknown, expired, or deleted key. |
| 401 | invalid_token | Missing or expired OAuth token. The response carries WWW-Authenticate pointing at the protected-resource metadata. |
| 403 | insufficient_scope | The OAuth token lacks the mcp scope. Re-authorize. |
| 429 | rate_limited or usage_exceeded | Too many requests on an API key. Honour Retry-After (seconds). |
A JSON-RPC request that omits the required protocol headers or the _meta envelope fails with JSON-RPC error -32020. See Any other client for the full header set.
On HTTP endpoints
Product HTTP endpoints return one JSON shape:
{ "error": { "code": "PLAN_LIMIT_REACHED", "message": "Your plan includes 3 projects. Upgrade to add more.", "hint": "..." } }| Status | Meaning |
|---|---|
| 400 | Validation or an impossible action, such as archiving the last active project (CANNOT_ARCHIVE_LAST_PROJECT). |
| 402 | Out of credits (INSUFFICIENT_CREDITS), or a plan gate (PLAN_UPGRADE_REQUIRED, PLAN_LIMIT_REACHED). Plan gates add a denial object with feature, currentPlan, requiredPlan, and for limits { name, allowed, current }. |
| 502 | The data provider failed. |
| 503 | Payments are not configured on this deployment. |
Rules of thumb for agents
- Never retry a 402 or a plan gate; the outcome will not change until the user acts.
- Treat
-32020as a client bug, not a server outage. - On 429, wait for
Retry-Afterand continue; the limit is per minute. - When a paid call fails after the balance check, nothing was charged.