> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hypergsc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Handle HyperGSC errors and tool limits

> Resolve MCP authorization, property access, plan, quota, input, and Google connection errors without losing the context of the requested SEO task.

A tool can be discoverable and still be unavailable for the current request. HyperGSC checks scope, property access, plan, provider readiness, and quota at execution time.

## Common error codes

| Code | Next action |
| - | - |
| `UNAUTHENTICATED` | Complete browser sign-in and authorize the connection again. |
| `SCOPE_REQUIRED` | Reauthorize with the required scope; research writes need `projects:write`. |
| `PROPERTY_NOT_ENABLED` | Enable the property in HyperGSC Connections and save changes. |
| `CONNECTION_ACCESS_REQUIRED` | Check that the connected Google account has the necessary property access. |
| `GOOGLE_RECONNECT_REQUIRED` | Reconnect Google from Connections. |
| `PLAN_REQUIRED` | Use a tool available to the current account or report the limitation. |
| `PLAN_LIMIT_REACHED` | Read current usage and the returned reset information. |
| `PROPERTY_LIMIT_REACHED` | Reduce the enabled selection to the account's current limit. |
| `INVALID_INPUT`, `INVALID_QUERY`, `INVALID_DATES` | Read the current schema and correct the arguments. |
| `GOOGLE_QUOTA_EXCEEDED` | Respect Google's quota response and retry only when appropriate. |
| `GOOGLE_UNAVAILABLE` | Preserve the request context and retry a bounded request later. |

A response may use other operation-specific codes. Preserve the returned code, message, limits, and readiness date rather than replacing them with a guessed explanation.

## Tool results and transport failures

Tool execution errors can be returned as MCP results with `isError: true`, structured content, and a JSON text representation. Do not assume a successful HTTP transport status means the tool succeeded.

Authentication or protocol failures can occur before tool execution and need separate client handling.

## Check availability before large requests

Call `get_capabilities` and `get_usage` before a large analysis or paid-provider batch. Tool discovery includes availability metadata under `_meta["com.hypergsc/availability"]`.

A cached catalog can become stale after quota use, plan changes, server updates, or authorization changes.

## Keep requests bounded

Inspect no more than ten URLs in a batch. Analytics requests have row limits and source coverage limits. Provider research can consume quota for dispatched failures as well as successful responses.

Do not repeatedly retry an invalid request or an exhausted allowance. Reuse an idempotency key when retrying the same SEO-change record, and refresh versioned state before retrying a conflicting deletion.

See [troubleshooting](https://docs.hypergsc.com/troubleshooting.md) for user-facing fixes and [plans and usage](https://docs.hypergsc.com/reference/plans-and-usage.md) for shared allowances.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.