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.