Handle errors and unavailable data

Check the transport, the tool result, and the IQRush payload before treating a response as data. A successful HTTP status can still contain an application error.

Recover by the kind of problem

Signal	Likely meaning	What to do
HTTP 401; `auth_missing`	Missing, expired, or revoked authorization.	Refresh or reconnect through the documented authorization flow.
HTTP 403	Access or account eligibility is refused.	Check the account and applicable permissions.
HTTP 404; `not_found`	Project, run, or resource unavailable to the caller.	Rediscover the project and run. At the MCP transport level, an expired session can also require reinitialization.
HTTP 400/422; `config_invalid`	Invalid parameter, value, or combination.	Read the field named in the error and correct the request.
Unknown MCP argument	The tool does not declare the argument.	Refresh `tools/list`; do not assume it was applied.
`insufficient_data`	Not enough usable data for this operation.	State the limitation; check run history and selection.
`analytics_capacity_exceeded` or HTTP 503	The analytical service is busy.	Retry after the supplied delay, if present.
`network_error`, timeout, transient 5xx	Request failed in transit or temporarily at the service.	Use bounded retries and keep the same scope.
HTTP 429, if returned	A request limit was reached.	Honor `Retry-After`; reduce request frequency.

The HTTP error body can use detail, while a measurement error uses error.code, error.message, and error.details. MCP can wrap an HTTP failure as http_error with details.status_code. Preserve the code in your logs and provide a useful message to the user.

What an error response looks like

These are selected fields from observed Dev MCP responses. Project and run IDs have been replaced with placeholders. The surrounding response can contain additional fields.

Invalid metric

A citation request with an unsupported metric returns a validation error:

{
  "data": null,
  "error": {
    "code": "http_error",
    "message": "HTTP 422: /projects/PROJECT_ID/runs/RUN_ID/citation-score -- metric: Input should be 'share' or 'coverage'",
    "details": {
      "status_code": 422,
      "detail": "metric: Input should be 'share' or 'coverage'"
    }
  }
}

Correct metric to share or coverage. Retrying the same invalid value will not help.

Invalid run ID

Passing NOT_A_RUN_ID to get_run returns:

{
  "data": null,
  "error": {
    "code": "http_error",
    "message": "HTTP 400: /projects/PROJECT_ID/runs/NOT_A_RUN_ID -- run_id must be a UUID",
    "details": {
      "status_code": 400,
      "detail": "run_id must be a UUID"
    }
  }
}

Use the exact run_id returned by list_runs. Both errors above arrived with the outer MCP isError flag unset or false. Your client must inspect the decoded payload’s error field as well.

Required analysis input missing

An empty domain passed to get_factor_analysis returned an application-level error:

{
  "data": null,
  "error": {
    "code": "config_invalid",
    "message": "domain is required",
    "details": {}
  }
}

Supply a domain from the selected run’s citation results. This payload uses config_invalid; it is distinct from the HTTP validation errors above. The outer MCP isError flag was false in this observed case too.

No linked Google property

An unavailable integration can return a normal response rather than an error. For example, list_ga4_properties returned:

{
  "project_id": "PROJECT_ID",
  "linked": false,
  "properties": []
}

Explain that no Google property is linked to this project. Do not report zero traffic or keep retrying the request.

Do not retry every empty result

An unready run may become ready. A transient capacity error may clear. An invalid filter, inaccessible project, unindexed name, or unavailable historical data needs a different action. Use empty_reason and any not_available or unavailable_reason fields rather than treating every empty response alike.

Retry politely

For retryable read failures, use a small maximum attempt count, increasing delays, and a maximum total wait. Honor a valid Retry-After header. Avoid repeatedly starting all requests in a large report at once. After the limit is reached, show what could not be retrieved and let the user retry. This edition does not publish a verified account-wide requests-per-minute allowance. Do not infer a commercial limit from a server configuration default. Ask your IQRush contact for the operating limits assigned to a high-volume integration.

Make support requests reproducible

Include the tool or route, environment, request time, project and run IDs, nonsecret parameters, error code, and any response identifier supplied. Remove tokens, session headers, private answer text, and unnecessary customer data before sharing logs. Next: Availability and limits.

Get started

Connect securely

Read measurements

Build dependable integrations

Build reports

Report recipes

Reference

Session and discovery

Visibility measurements

Sources and evidence

Changes and trends

Google data

Pages and report planning

HTTP operations

Handle errors and unavailable data

Recover by the kind of problem

What an error response looks like

Invalid metric

Invalid run ID

Required analysis input missing

No linked Google property

Do not retry every empty result

Retry politely

Make support requests reproducible

​Recover by the kind of problem

​What an error response looks like

​Invalid metric

​Invalid run ID

​Required analysis input missing

​No linked Google property

​Do not retry every empty result

​Retry politely

​Make support requests reproducible

Recover by the kind of problem

What an error response looks like

Invalid metric

Invalid run ID

Required analysis input missing

No linked Google property

Do not retry every empty result

Retry politely

Make support requests reproducible