錯誤代碼
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，其中的 code 例如為 INTERNAL_SERVER_ERROR）。請檢查這兩種情況：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 範圍內的代碼來自用於匯入或連結發布平台商家資訊的 Connected Accounts 端點。這些代碼會以巢狀形式出現在 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
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 時，必須自行執行相同的兩項檢查：先檢查狀態碼，再檢查回應承載資料：
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 會為您執行這兩項檢查：它會將每個 HTTP 狀態對應至具型別的例外，若 200 主體內含錯誤承載資料，也會拋出例外。