Housing Market API 集成指南

参考表格、端点说明、错误代码和示例均根据 API 规范生成，在所有语言版本中均保留英文。名称、参数和代码在各处完全相同。

错误代码

每个错误都有一个 HTTP 状态码和一个包含 error 和 message 的 JSON 正文。

请根据 error 进行分支处理，切勿根据 message：消息是给人看的，可能会变化。今后可能会新增代码，因此请将未知代码视为其所附带的 HTTP 状态码所表示的失败。

HTTP 403 有四种不同的代码。请读取代码以确定是哪一种：ip_not_allowed、key_paused、country_not_entitled 或 upgrade_required。

Code	HTTP	Meaning	What to do
`invalid_cursor`	400	The cursor is malformed, expired, or was issued for a different key or different filters.	Start again from the first page with the filters you want.
`invalid_parameter`	400	A parameter is unknown, malformed or out of range.	Check the parameter name and value against the reference. Unknown parameters are refused, not ignored.
`unauthenticated`	401	No key was sent, or the key is not recognised or has been revoked.	Send the key in the x-api-key header. Check it in the console.
`country_not_entitled`	403	The country is not part of your subscription.	Add the country in the console. The same key then covers it.
`ip_not_allowed`	403	The key is valid but the request came from an address that is not registered for it.	Call GET /v1/ping to see the address we see, then register it in the console.
`key_paused`	403	The key is paused, for example after an unpaid renewal or while a payment dispute is reviewed.	Open the console to see why. The key resumes automatically once the payment is settled.
`upgrade_required`	403	The endpoint belongs to the Advanced tier and the key is Standard.	Upgrade in the console. The same key then covers Insights.
`not_found`	404	The path does not exist, or the listing it names does not exist in that country or has been withdrawn.	Check the path against the reference. For a listing, check the id and the country, and walk the listings again.
`method_not_allowed`	405	The method is not allowed for this path. Every endpoint is GET.	Use GET.
`quota_exceeded`	429	The daily or monthly quota for the key has been used.	Wait for the Retry-After period. If you regularly need more, contact support.
`rate_limited`	429	The per-minute request limit for the key has been reached.	Wait the number of seconds in the Retry-After header, then retry.
`internal_error`	500	An unexpected error on our side.	Retry later. If it persists, contact support.
`not_configured`	503	The service is not configured to accept this request yet.	Retry later.
`service_unavailable`	503	The service is temporarily unable to answer.	Retry later.