Errors

Every error is JSON with one shape. The HTTP status tells you the class; error.code tells you exactly what to do.

{"error": {"code": "bad_request", "message": "state: 'TEXAS' is not a two-letter code"}}

Status	code	Meaning
400	`bad_request`	Unknown parameter, bad value, bad cursor, unsupported format. The message names the parameter.
401	`unauthorized`	No key, malformed header, unknown or revoked key.
403	`plan_required`	Feature needs a higher plan (inactive rows, export format).
404	`not_found`	No listing / brokerage with that id.
429	`rate_limited`	Requests per minute exceeded. Honor `Retry-After`.
429	`quota_exceeded`	Monthly records used and no overage. Includes `error.quota`.
500	`server_error`	Our fault. Retry with backoff; if it persists, email support with the request id from the logs.
503	`unavailable`	Maintenance or dependency outage. Retry.

Retry guidance

Retry 429 rate_limited, 500 and 503 with exponential backoff (1 s, 2 s, 4 s, max 5 tries). Never retry 400, 401, 403, 404 or quota_exceeded without changing something. MCP tool errors carry the same codes inside the tool result with isError: true.