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

# 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.

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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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](/developers/guides/22-availability).


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