Errors

Every error, on the REST API and the MCP server alike, uses one JSON envelope with a stable, machine-readable code:

json

{ "error": { "code": "invalid_request", "message": "Malformed JSON body" } }

Branch on code, not on the human-readable message (which may change).

Codes

Code	HTTP	Meaning
`invalid_request`	400	Malformed body or invalid parameters
`unauthorized`	401	Missing, unknown, disabled, or exhausted key
`unparseable_query`	422	The natural-language query couldn't be understood
`rate_limited`	429	Too many requests, see Rate limits
`no_data`	404	The request was valid but matched nothing
`not_found`	404	Unknown route
`method_not_allowed`	405	Wrong HTTP method for the route
`timeout`	504	An upstream lookup exceeded its deadline
`unavailable`	503	A dependency was temporarily unreachable
`internal`	500	Unexpected server error

rate_limited and timeout are transient; retry after a short backoff. rate_limited responses include a Retry-After header.
unavailable is also transient; back off and retry.
invalid_request, unauthorized, and unparseable_query are your side, fix the request rather than retrying it.
no_data isn't a failure: the query was fine, there just wasn't a match.