MCP docs › Jobs & errors

Jobs, errors and quotas

The three behaviours that trip agents up, spelled out.

1. Long runs return a job handle

Every tool starts a job. If it finishes within about 25 seconds you get the rows inline. Otherwise the call succeeds with:

{
  "status": "running",
  "job_id": "abc123",
  "tool_flow": "tool-run",
  "suggested_wait_s": 5
}

That is not an error. Wait a few seconds, then poll:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_job_result",
    "arguments": {
      "job_id": "abc123",
      "tool_flow": "tool-run"
    }
  }
}

Repeat until status is done (results attached) or error. Never start a second run of the same tool for the same request — it charges quota twice. Lost the id? Call list_jobs.

tool_flow is scrape for google_maps_search and tool-run for every other tool; it is always included in the running response, so copy it from there.

2. Error codes

Code	Meaning	What to do
`-32001`	Auth, quota or scope: invalid key, monthly cap reached, or the tool is outside a scoped token's allow-list.	Do not retry. Call `account_status` to find out which of the three, then tell the user.
`-32602`	Invalid parameters. The message names the accepted arguments and gives a working example.	Fix the arguments and call again.
`-32601`	Unknown tool. Aliases and near-miss spellings are resolved automatically; a genuine miss lists the closest real names.	Use a suggestion, or call `find_tool`.
`-32000`	Upstream failure — the target site blocked or timed out the run.	One retry after a pause is reasonable; otherwise report a source-side failure.

3. Quotas and clamping

Runs are metered monthly per account and attributed to a source (web, API, MCP). Per-run row counts are clamped to the plan tier, so asking for more rows than the plan allows returns the ceiling instead of an error — read count in the result rather than assuming you got what you asked for. account_status reports the plan, usage and remaining runs; see pricing for the tiers.

Empty is usually an answer. No businesses matched, or nobody advertises under that name in that region — the run completed and found nothing. Tools that were actually blocked raise an error instead, so an empty success can be reported to the user as a finding.