Errors, pagination and revalidation
Handle public API responses without duplicating requests or guessing cursor values.
Read an error
REST failures and MCP tool errors use this body shape:
{
"error": {
"code": "INVALID_PARAMETER",
"message": "An explanation of the invalid request."
}
}This is an illustrative error message. Branch on the stable code; message wording can change. Consult the OpenAPI specification for the complete code list and route-specific responses.
| Code | Client action |
|---|---|
MISSING_PARAMETER or INVALID_PARAMETER | Correct the request using the current schema. |
CONFLICTING_PARAMETERS | Remove incompatible options; for a changed search, start again without its cursor. |
LISTING_NOT_FOUND or PLACE_NOT_FOUND | Show that the requested resource is unavailable. Do not present cached details as current. |
RATE_LIMITED | Wait for the HTTP Retry-After interval before retrying. |
UPSTREAM_ERROR or INTERNAL_ERROR | Show a temporary failure and use bounded retries. |
MCP tool errors are reported in tool results; inspect the result rather than assuming an HTTP success means the requested operation succeeded.
Follow listing-search pages
- Send the initial keyword or city-browse query.
- Read the
resultsand the response'snextCursor. - If
nextCursoris present, return it unchanged ascursorwith the same search parameters. - Stop when no
nextCursoris returned.
Cursors are opaque. Do not decode, modify or reuse one for a different query, filter, market or sort. Do not combine page and cursor. Follow pages promptly and deduplicate results by listing id if your interface combines them.
A changed search starts without a cursor. If a cursor is rejected, start a fresh search rather than repeatedly sending it. When totalIsLowerBound is true, the displayed total is a lower bound, not an exact count; narrow a broad search to explore more relevant results.
Proximity searches
Send lat, lng and radiusKm together. Proximity results are nearest-first and have one page; do not send cursor, page, q, city or sort with that mode. Read nearby.truncated to see whether additional matches fall outside the returned set.
Treat distanceKm as a distance to the public listing location. Locations are approximate by default unless the seller opts in to sharing an exact point.
Revalidate an unchanged request
Keep the returned ETag and send it exactly as received in If-None-Match when requesting the same resource again. A 304 response has no body; retain your previously stored representation. Respect the response's Cache-Control policy. A revalidation request can still be rate limited.