錯誤代碼
Listings API 的 HTTP 狀態碼、商家資訊與 Social 的 SYxxxxx 錯誤代碼,以及 v4 API 傳回的 3 種錯誤回應格式。
Listings API 使用標準 HTTP 狀態碼回報請求結果。錯誤代碼以 SY 為前綴,包含在錯誤的 message 字串中,格式為 SYxxxxx: <human-readable reason>。
HTTP 狀態碼
HTTP status code summary
3 種回應結構
大多數失敗回應會包含 errors 陣列,位於頂層或巢狀置於操作結果中,如下方各節所示。少數失敗回應則會傳回單一 error 物件:速率限制(429)以及部分請求層級的失敗(400/500,並帶有值為 INTERNAL_SERVER_ERROR 等內容的 code)。請同時檢查這兩種情況:errors 是陣列,error 是物件。
1. 請求層級:頂層的 errors[]
驗證、授權及請求格式錯誤等失敗會在操作執行前中止處理。這些失敗會傳回對應的 4xx 狀態碼(如上所述),並將錯誤置於回應的頂層。
{ "data": { "createLocation": null }, "errors": [{ "message": "SY90005: Invalid Token" }]}2. 寫入驗證:巢狀的 data.<operation>.errors[]
建立、更新或發布請求若在其他方面格式正確,便會傳回 HTTP 200。若輸入違反業務規則,失敗資訊會回報在該操作自身酬載下的 data.<operation>.errors 中,採用巢狀結構。成功時,此陣列仍會存在,但內容為空("errors": [])。
{ "data": { "createLocation": { "errors": [ { "message": "SY10126: City is Mandatory" }, { "message": "SY10010: state_iso" } ], "location": null } }}3. 閘道層級:單一頂層 error 物件
速率限制和非預期的閘道故障會在轉換前中止處理,並傳回一個 error 物件,其中包含 code、message 和 correlation_id。關於 429 的回應主體,請參閱下方的 rate_limited。
寫入時務必讀取 data.<operation>.errors,即使收到 200 且 data.<operation> 物件已有內容也一樣:寫入可能部分失敗,並在此處回報。
402 Payment Required 回應沒有 error 包裝層:code、message、doc_url,以及有待付款發票時的 pay_url,都位於頂層。請參閱下方的 payment_required。
重試寫入並非沒有代價
v4 API 不支援 Idempotency-Key:此標頭會被忽略,而且沒有任何端點會偵測重複寫入。建立、更新或發布呼叫即使逾時或傳回 5xx,仍可能已在伺服器上完成提交,因此未經確認就重試可能會產生重複的地點、貼文或評論回覆。
讀取操作可直接採用退避機制重試。寫入操作則應先讀回資料:使用您可掌握的索引鍵(storeId、商店代碼、互動的回覆清單)查詢記錄,只有在確認記錄不存在時才重複呼叫。
常見代碼
Common SY error codes
SY10xxx 範圍內的驗證代碼對應至特定輸入欄位;message 會指出未通過驗證的欄位或規則。SY90xxx 範圍內的身分驗證與授權代碼適用於整個請求,會出現在回應的最上層,並附帶相應的狀態。
已連結帳戶代碼
SY810xx 範圍內的代碼來自用於匯入或連結發布平台商家資訊的已連結帳戶端點。這些代碼會以巢狀結構出現在 HTTP 200 的回應主體中(上方的回應結構 2),因此即使狀態表示成功,也請讀取 data.<operation>.errors。
SY810xx connected-account and import codes
Social 代碼
SY950xx 範圍內的代碼來自 Social 端點:品牌、連線和社群貼文。與已連結帳號的代碼一樣,這些代碼會以巢狀結構出現在 HTTP 200 的回應主體中,因此即使狀態表示成功,也請讀取 data.<operation>.error(批次路由還須讀取 data.<operation>.errors)。
SY950xx Social codes
SY95042 和 SY95044 是方案使用權限不足所導致的錯誤,不是輸入錯誤:若未變更方案就重試,仍會發生相同的錯誤。SY95045、SY95046、SY95049 和 SY95052 是輸入錯誤,可在下一個請求中修正。
Listings 使用權限代碼
Listings plan codes
Listings scan 代碼
SY830xx 範圍內的代碼來自 listings scan 端點。無法建立掃描時,錯誤會以巢狀形式出現在 HTTP 200 的回應本文中:請讀取 data.createListingScan.errors,並確認 scan 為 null。SY83005 是例外:讀取不存在的掃描時,會傳回 404。
SY830xx listings scan codes
使用唯讀金鑰呼叫建立端點時,會改為收到 SY90016,其狀態為 HTTP 400。立即重試相同請求時,SY83001、SY83002 和 SY83004 不會改變,而 SY83010 則適合等待一段時間後重試。
rate_limited
429 Too Many Requests:此帳戶已超過其方案的速率限制。本文是標準錯誤回應,包含 retry_after_seconds 提示、可在支援請求中提供的 correlation_id,以及連回本節的 doc_url:
{ "error": { "code": "RATE_LIMITED", "message": "Too many requests. Slow down.", "retry_after_seconds": 30, "correlation_id": "9f2c1e64-2b1a-4b0e-9f1a-2c7d5e8a1b3c", "doc_url": "https://listingsapi.com/docs/error-codes#rate_limited" }}請依 retry_after_seconds(或存在時的 Retry-After 標頭)指定的時間等待,再使用指數退避方式重試。各方案的限制與退避實作範例,請參閱速率限制。
payment_required
402:此帳戶最近一次付款未成功,因此所有 /api/v4 端點均已暫停。如果有未付款發票的 Stripe 頁面,本文會包含該頁面的 pay_url,而 X-Error-Code 回應標頭會包含相同的 code。您仍可開啟儀表板中的帳單頁面進行付款。
{ "code": "payment_required", "message": "This account has an unpaid invoice, so API access is paused. Pay the invoice to restore access.", "pay_url": "https://invoice.stripe.com/i/acct_123/test_abc", "doc_url": "https://listingsapi.com/docs/error-codes#payment_required"}最後一張未結清發票付款完成後,存取權限會在 1 分鐘內恢復。如果首次付款失敗後 3 天,發票仍未付款,Listings 訂閱就會取消,帳戶的地點也會封存。如果帳戶另有有效的 Social 訂閱,則會保留 Social 存取權限;否則帳戶會關閉,其 API 金鑰也會失效。
social_payment_required
402:Social 訂閱最近一次付款未成功,因此 Social 端點(/api/v4/social/*)已暫停。Listings 端點仍可正常使用。本文的欄位與 payment_required 相同,並包含 "code": "social_payment_required"。如果首次付款失敗後 3 天,發票仍未付款,Social 訂閱就會取消,帳戶的品牌也會封存。沒有 Listings 訂閱的帳戶會關閉,其 API 金鑰也會失效。
開發者入口網站的控制平面錯誤
開發者入口網站中的帳戶與金鑰管理端點(儀表板本身的 API 路由)會傳回單一的結構化錯誤回應,其格式與上述 REST errors[] 格式不同。每個 code 都包含一個 correlation_id 和一個 doc_url,後者會連結至本頁對應的章節。
{ "error": { "code": "AUTH_INVALID_KEY", "message": "Session is invalid or expired.", "correlation_id": "9f2c1e64-2b1a-4b0e-9f1a-2c7d5e8a1b3c", "doc_url": "https://listingsapi.com/docs/error-codes#auth_invalid_key" }}auth_missing_key
401:未提供憑證。請重新登入,或以 Authorization: API <your-key> 傳送您的金鑰。
auth_invalid_key
401:工作階段或金鑰無效或已過期。請重新驗證身分,或從儀表板重新核發金鑰。
auth_insufficient_scope
403:憑證有效,但無權執行此操作。僅具讀取權限的金鑰無法呼叫寫入端點;如有需要,請核發具寫入權限的金鑰。
not_found
404:請求的資源或透過 ID 指定的資源不存在。
conflict
409:請求與資源目前的狀態衝突(例如,撤銷已撤銷的金鑰)。
validation_failed
422:請求主體未通過驗證。回應中的 field 和 details 會指出有問題的輸入。
internal_error
500:發生非預期的伺服器端錯誤。讀取操作請採用指數退避策略重試;寫入操作則請先讀回該筆記錄(請參閱重試寫入並非沒有代價)。若您聯絡支援人員,請提供 correlation_id。
dependency_unavailable
503:API 所依賴的服務暫時無法使用。請採用退避策略重試。
關於 429,請參閱上方的 rate_limited。
在程式碼中處理錯誤
請先檢查 HTTP 狀態;若是寫入操作,接著檢查回應主體中是否有巢狀的 errors 陣列:
from listingsapi import APIError, ListingsAPI client = ListingsAPI(api_key=os.environ["LISTINGSAPI_KEY"]) try: location = client.locations.create(input=payload)except APIError as e: # Raised for a non-2xx status (AuthenticationError, ValidationError, and # so on) and for an error payload returned inside a 200 body. raise RuntimeError(f"Listings API error: {e}") from e直接使用 HTTP API 時,您必須明確執行相同的 2 項檢查,先檢查狀態碼,再檢查回應酬載:
resp = requests.post( "https://listingsapi.com/api/v4/locations", headers={"Authorization": f"API {os.environ['LISTINGSAPI_KEY']}"}, json=payload, timeout=30,)resp.raise_for_status()body = resp.json() op = (body.get("data") or {}).get("createLocation") or {}if op.get("errors"): messages = [e["message"] for e in op["errors"]] raise RuntimeError(f"Listings API error: {messages}")Python SDK 會為您執行這 2 項檢查:它會將每個 HTTP 狀態對應至特定類型的例外,也會在 200 主體內傳回錯誤酬載時引發例外。