Errors over MCP - Investorlift Data Services

A failure inside a tool is not a transport error. The HTTP status stays 200, and the JSON-RPC result is a normal tool result with isError: true. content[0].text reads <code>: <detail> <recovery>. structuredContent.error carries the problem body the REST API returns for the same failure. It also carries a recovery sentence and any facts that save a round trip. For example, godmode_deals_summary at a point in New York:

{ "isError": true,
  "content": [{ "type": "text", "text": "outside_coverage: the point 40.7128, -74.006 is outside every loaded market's point tolerance (loaded: hou within 2 mi of its bbox, phx within 20 mi of its bbox); see meta.coverage[].bbox and point_tolerance_miles on any list response. No data at this location; the loaded markets and their areas are listed in markets[] when present, and in meta.coverage[] on any list response." }],
  "structuredContent": { "error": { "type": ".../guides/concepts/errors#outside_coverage", "title": "Outside coverage", "status": 422, "code": "outside_coverage", "instance": "/mcp", "request_id": "ca4c1a3e-...",
    "detail": "the point 40.7128, -74.006 is outside every loaded market's ...", "recovery": "No data at this location; ...",
    "markets": [ { "market": "hou", "state": "TX", "bbox": [-95.95790786, 29.501148, -94.91426317, 30.166826], "point_tolerance_miles": 2, "universe_kind": "county" }, "... one entry per loaded market" ] } } }

The codes a tool can return. The last column is the recovery sentence itself, word for word. So what a client shows a reader is what the code carries:

Code	Status	When	`recovery`
`validation_error`	400	a parameter failed validation, an exactly-one group was empty or doubled, `limit` over the format’s cap, the byte guard	Fix the parameters named in `errors[]` and send the request again.
`unknown_parameter`	400	the encoded query carries a parameter the underlying route does not define	Remove the parameter, or write the list as comma-separated values or repeated keys, for example `kind=flip,hold`.
`invalid_cursor`	400	the cursor is undecodable, or the API issued it for another query, sort, weight set or dataset version	Restart from page 1 without `cursor`; the data refreshed or the query changed.
`geometry_required`	400	no geometry where the tool needs one	Pass one geometry: `lat` and `lng` with `radius_miles`, `bbox`, `property_id`, `zip` (a list) or `city`.
`geometry_conflict`	400	`radius_miles` with `bbox`, or `property_id` beside either. A lone latitude or longitude. `zip` beside `city`, or a place beside `radius_miles`, `bbox` or `property_id`. `zip` / `city` on `godmode_buyers_match`	Send one geometry only: lat and lng with `radius_miles`, bbox alone, `property_id` with `radius_miles`, or zip or city. On the coverage route, pass one place: lat and lng, county, zip or market.
`sort_requires_point`	400	`sort: "distance"` with a `bbox`, a `zip` or a `city` and no point	Add `lat` and `lng` or `property_id`, or drop `sort=distance` and take the default date order.
`market_required`	400	the id exists in more than one loaded market. Or you called `godmode_lenders_top`, which ranks inside one market, with no `market` on a host with several loaded markets. `markets[]` lists them	The id exists in each listed market, or the list ranks inside one; pass market.
`plan_limit`	403	a `limit` over the plan’s largest page. A `weeks` over 52 on Free and Starter on `godmode_market_changes` (`limit: "weeks"`, `cap: 52`). A search wider than the plan allows. The name-search day cap. The body names the limit	Narrow the request to what the body names as the limit, or upgrade the plan in the developer console.
`quota_exceeded`	403	on a client that negotiates 2026-07-28, you spent the period’s credits: the allowance, or on Growth and Scale the ceiling. The tool sends no page and charges nothing. At the line, every charged tool answers it until the period resets or the plan changes. That includes a re-read of a record already held. The handshake and the uncharged tools keep answering. A legacy client meets it as a real `403` before the tool runs (below)	Upgrade the plan in the developer console, or wait for the billing period to reset.
`not_found`	404	no such deal, investor, parcel, agent, lender, listing or company in any loaded market	Check the path and the id; the entity is in no loaded market, or the route does not exist.
`gone`	410	a retired investor, agent or lender id, with no successor	This id is retired and has no successor; look the investor, agent or lender up by name.
`outside_coverage`	422	the point or viewport misses every market’s tolerance. `markets[]` carries the boxes. Also a `zip` or `city` that no parcel of a loaded market carries, on the deals, investors and wholesale tools. The body then carries `zips_unknown` or `city` beside `markets[]`. Also a ZIP, city or county on `godmode_lenders_top` outside the counties its market’s lender registry covers (`meta.coverage[].lenders.counties`). The body then carries `counties_covered`. A ZIP of an unloaded county is not a place with no lending	No data at this location. Read the loaded markets and their areas from `markets[]` when present, and from `meta.coverage[]` on any list response.
`addresses_unavailable`	422	`address` on `godmode_property_lookup` while no market has a published address table. `address_as_of` is then null on every market in `godmode_coverage`	Resolve by lat / lng or apn, or retry once `coverage[].address_as_of` carries a date.
`listings_unavailable`	422	`listing_status` on the investor deals tool, or `source: mls` on the comps tool, for a market with no listing tables	Not published for this market yet. The API still serves deal, investor and property rows with the listing block null, and the comps from the deed registry alone.
`agents_unavailable`	422	any agent path for a market with no agent registry	Not published for this market yet. The API still serves the listing agents on deal and property rows, without ids.
`lenders_unavailable`	422	a lender tool for a market with no lender registry (`meta.coverage[].lenders` null there). The borrowers tool on a registry built before its borrower match. The nearby tool, `period` on the top tool, or the loans tool’s `foreclosed`, `cell` or geometry on a registry built before the place rankings. The same on a host without the h3 extensions	Not published for this market yet, or its registry predates the borrower match or the place rankings the request asked for. The API still serves the financing block on parcels where the slice is.
`wholesale_unavailable`	422	a wholesale tool or the Investorlift filters for a market with no wholesale tables	Not published for this market yet; deal, investor and property rows are still served with their wholesale blocks null.
`cash_sale_unavailable`	422	the `cash-buyer` quicklist or `filters.sale.cash_sale` on `godmode_property_search` for a market whose coverage row carries `sale_mortgage_measured: false`. In that market the delivery records a purchase mortgage on fewer than one priced last sale in five, so `cash_sale_proxy` is null on every parcel	Not measured for this market: drop cash-buyer and `sale.cash_sale`. Where `auction_counted` is true, `bought_auction_kind`, `buys_at_auction` and `buys_reo` are the measured cash signals.
`rate_limited`	429	you spent the plan’s requests a minute or a day. The gateway answers before it reads the message (see below)	Retry after `retry_after` seconds.
`internal_error`	500	anything unexpected. The API echoes nothing from the database	Retry once. If it occurs again, report the `request_id`.
`database_unavailable`	503	the API cannot reach the database	Retry with backoff. The database was unreachable and the API did not run the request.
`pool_saturated`	503	no pooled connection in 2 s, or the per-pod in-flight cap	Retry in a second. The service is at capacity and did not run the request.
`ledger_unavailable`	503	the API cannot reach the credit ledger. `retry_after` is on the body	Retry after `retry_after` seconds. The API charged nothing and served nothing.
`statement_timeout`	504	the query passed the 10 s statement timeout	Narrow the radius or add filters. The query exceeded 10 seconds.

Two details about errors[]. The tool encodes the arguments to the /v1 querystring before the route’s validator runs. So a geometry failure names the wire field, not the tool’s input field. A lone latitude comes back as geometry_conflict with param: "lng" and the detail “lat and lng must be given together”. The tool’s schema does not refuse an argument it does not define. The tool encodes it, and the route refuses it as unknown_parameter, which is how a bracketed list reads. godmode_coverage is the exception: it builds no wire query and validates none. So it drops an argument it does not define without a word. Three real bodies, trimmed to the parts that differ:

{ "code": "validation_error", "detail": "One of investor_id, name is required.", "errors": [ { "param": "investor_id", "message": "exactly one of investor_id, name", "code": "missing" }, { "param": "name", "message": "exactly one of investor_id, name", "code": "missing" } ] }
{ "code": "unknown_parameter", "detail": "Unknown parameter: kind[]. List values are comma-separated (kind=flip,hold) or repeated keys (kind=flip&kind=hold), never bracketed." }
{ "code": "market_required", "detail": "wsr_eea85093d3ae exists in 2 loaded markets (hou, phx); pass market=.", "errors": [ { "param": "market", "message": "one of hou, phx", "code": "market_required" } ], "markets": ["hou", "phx"] }

Ambiguity is not an error. An APN that names distinct parcels, and a name that matches several entities, come back as a success with resolved: false and candidates[]. Rate limits and credits. The gateway enforces the plan’s requests a minute and a day. So a burst answers 429 with the problem body (code: "rate_limited", request_id) and a Retry-After header, and the gateway never reads the JSON-RPC message. A key whose plan ended answers 403 subscription_required, and a key whose card failed more than seven days ago answers 403 payment_overdue, the same way. A tools/call costs what its route costs (Plans and limits). On a client that negotiates protocol 2026-07-28, that cost is the ledger’s figure. The figure is one credit per deal, investor or parcel new to the account, plus the tool’s base, and nothing for a record already seen. Every result reports it in meta.credits.charged, beside used, line and period_end. Those three are the period’s count after the call, the figure it stops at, and when it resets, so a client can predict the stop. See Keys and headers. A spent allowance, or on Growth and Scale the ceiling, then arrives as a quota_exceeded tool result. The tool sends no page and charges nothing. Every charged tool answers so until the period resets or the plan changes, a re-read included. The handshake and the uncharged tools keep answering. The API writes a legacy client’s single-frame stream before the tool runs. So it charges such a client per call, refused or served, at the largest possible cost of its page. That cost is the tool’s base plus the asked page, clamped to 50 and the plan’s largest page. On a legacy client, the API refuses a call whose weight passes the line as a real 403 quota_exceeded. The refusal comes before the tool runs and before the API counts anything. It reads the envelope only for the tool’s name and the asked page, which set the weight. A call the tool then refuses, for example with a plan_limit or a validation error, still costs that weight. So on a legacy client, ask for the plan’s page or less. initialize, tools/list, resources/read and prompts/get cost nothing. The SDK’s own refusals never reach a tool and carry no problem body. A schema failure is an isError result with one line of text and no structuredContent, for example

Input validation error: Invalid arguments for tool godmode_deal_get: data/deal_id must match pattern "^deal_[0-9a-f]{32}$"

. A typed id field carries its pattern in the schema, so the SDK catches a wrong prefix here, not the plan. That is why invalid_id is not in the table above. An unknown tool name is a JSON-RPC error instead, {"error": {"code": -32602, "message": "Tool godmode_nope not found"}}. Three more refusals occur at the transport: a batched array is 400, any Origin header is 403, and GET and DELETE are 405.

Partners and staff

On the internal host, rate limiting has two parts. Staff and contracted partners reach that host on the company network with a gm_ key. The API enforces the key budget (rpm, 120 by default) and the 240 per minute per (key, X-On-Behalf-Of) bucket before the SDK runs. So they answer 429 with the problem body, a Retry-After header and the x-ratelimit-* trio, and the API never reads the JSON-RPC message. The API charges the contact bucket, 30 per minute per (key, X-On-Behalf-Of), inside the tool wrapper each time the contact gate is open. So it arrives as an isError result with code: "rate_limited", retry_after and bucket on the body. The API spends the unit even when the record holds nothing. So a loop that opens one profile after another stops after 30 in a minute for that person. The header refusals of a contact-scope key, on_behalf_of_required and the prefixed-form validation_error, are on Keys and headers.

​Partners and staff

Partners and staff