錯誤代碼

Listings API 的 HTTP 狀態碼、商家資訊與 Social 的 SYxxxxx 錯誤代碼,以及 v4 API 傳回的 3 種錯誤回應格式。

Listings API 使用標準 HTTP 狀態碼回報請求結果。錯誤代碼以 SY 為前綴,包含在錯誤的 message 字串中,格式為 SYxxxxx: <human-readable reason>。

HTTP 狀態碼

HTTP status code summary

狀態含義常見的 SY 代碼Python SDK 例外
200 OK請求成功。寫入時也要檢查回應主體(請參閱下方說明)。--
400 Bad Request請求格式錯誤、無法剖析的篩選條件、無效的列舉值,或格式錯誤的 ID。SY90006, SY90001ValidationError
401 UnauthorizedAPI 金鑰遺漏、格式錯誤或已撤銷。還沒有金鑰嗎?開放申請時,您可以取得免費的沙箱單日通行證。SY90005AuthenticationError
402 Payment Required帳戶有未付款的發票,因此 API 存取已暫停。僅涉及 Social 的未付款發票只會暫停 Social 端點。請參閱 payment_required 和 social_payment_required。-APIError
403 Forbidden金鑰有效,但沒有存取此資源的權限。SY90003PermissionDeniedError
404 Not Found路徑或以 ID 指定的資源不存在。SY90002NotFoundError
422 Unprocessable Entity請求格式正確,但有值無法處理(例如未知或有歧義的類別)。-ValidationError
429 Too Many Requests您已超過方案的速率限制。請遵循 Retry-After 標頭。-RateLimitError
5xx伺服器錯誤。讀取操作可安全地採用退避機制重試;重複執行寫入前,請先參閱下方的寫入注意事項。SY90007InternalServerError

3 種回應結構

大多數失敗回應會包含 errors 陣列,位於頂層或巢狀置於操作結果中,如下方各節所示。少數失敗回應則會傳回單一 error 物件:速率限制(429)以及部分請求層級的失敗(400/500,並帶有值為 INTERNAL_SERVER_ERROR 等內容的 code)。請同時檢查這兩種情況:errors 是陣列,error 是物件。

1. 請求層級:頂層的 errors[]

驗證、授權及請求格式錯誤等失敗會在操作執行前中止處理。這些失敗會傳回對應的 4xx 狀態碼(如上所述),並將錯誤置於回應的頂層。

JSON
{  "data": { "createLocation": null },  "errors": [{ "message": "SY90005: Invalid Token" }]}

2. 寫入驗證:巢狀的 data.<operation>.errors[]

建立、更新或發布請求若在其他方面格式正確,便會傳回 HTTP 200。若輸入違反業務規則,失敗資訊會回報在該操作自身酬載下的 data.<operation>.errors 中,採用巢狀結構。成功時,此陣列仍會存在,但內容為空("errors": [])。

JSON
{  "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

代碼訊息HTTP 狀態含義
SY90005Invalid Token401API 金鑰遺漏、格式錯誤或已撤銷。請從儀表板重新核發金鑰,並以 Authorization: API <your-key> 傳送。
SY90001Not authorized to access this resource401 / 403此金鑰存取此資源的要求遭到拒絕。Python SDK 和 Node SDK 都會將此錯誤拋出為 AuthenticationError。
SY90002Invalid Id404 / 400無法解析路徑或引數中的 ID(通常是 relay ID 無效或未以 base64 編碼)。
SY10126City is Mandatory200(回應主體)輸入中遺漏了必要欄位(city)。
SY10010state_iso200(回應主體)stateIso 的值遺漏或無效。有效值請參閱國家與州/省端點。
SY10050At least one service area place is required200(回應主體)serviceArea.businessType 為 CUSTOMER_LOCATION_ONLY,且 placeInfos 為空。
SY10051Region code is required for CUSTOMER_LOCATION_ONLY business type200(回應主體)缺少 serviceArea.regionCode。請傳送由 2 個字母組成的國家代碼,例如 US。
SY10052Address is required when business type is CUSTOMER_AND_BUSINESS_LOCATION200(回應主體)此地點沒有 street 或 city。請傳送其中一項,或使用 CUSTOMER_LOCATION_ONLY。

SY10xxx 範圍內的驗證代碼對應至特定輸入欄位;message 會指出未通過驗證的欄位或規則。SY90xxx 範圍內的身分驗證與授權代碼適用於整個請求,會出現在回應的最上層,並附帶相應的狀態。

已連結帳戶代碼

SY810xx 範圍內的代碼來自用於匯入或連結發布平台商家資訊的已連結帳戶端點。這些代碼會以巢狀結構出現在 HTTP 200 的回應主體中(上方的回應結構 2),因此即使狀態表示成功,也請讀取 data.<operation>.errors。

SY810xx connected-account and import codes

代碼含義處理方式
SY81019找不到此金鑰所屬帳戶的使用者。請聯絡支援團隊:此帳戶沒有使用中的主要使用者。
SY81066connectedAccountId 不存在,或帳戶已封存。請從 GET /connected-accounts 重新讀取 ID。
SY81067無法解碼或解析 connectedAccountListingId。請從 connected-account-listings 記錄的 id 重新取得。
SY81068該商家資訊已連結至某個地點。請先中斷連結,或選擇其他商家資訊。
SY81069已連結帳戶的憑證已失效。請透過 connect-google 或 connect-facebook 重新連結帳戶。
SY81070此商家資訊不屬於您指定的已連結帳戶。請將每筆商家資訊與其來源帳戶配對。常見原因是取得商家資訊時,請求主體未包含 connectedAccountId,導致傳回其他帳戶的商家資訊。
SY81071建立地點時發生非預期的錯誤。請重試;若問題持續發生,請聯絡支援團隊。
SY81072建立地點時,在建構或儲存階段失敗。請重試;若問題持續發生,請聯絡支援團隊。
SY81073不支援匯入此商家資訊類型。僅可匯入 Google 和 Facebook 的商家資訊。
SY81074Google 未傳回此商家資訊的資料。請確認此商家資訊仍存在,且帳戶仍有管理權限。
SY81075已超過 Google 的 API 速率限制。請採用退避策略,稍後重試。
SY81076從 Google 取得商家資訊失敗。請重試;並檢查帳戶的 Google 權限。
SY81077無法從 Facebook 粉絲專頁判定國家。請在 Facebook 粉絲專頁的地址中加入國家,然後重試。
SY81078從 Facebook 粉絲專頁建構地點資料失敗。請重試;若問題持續發生,請聯絡支援團隊。
SY81081此商家資訊尚未設定主要類別。請為此商家資訊設定主要類別,然後重試。
SY81082不支援此商家資訊所屬的國家。支援的國家請參閱國家與州/省端點。
SY81083無法匯入 Google 商家資訊。請聯絡支援團隊並提供時間戳記。
SY81084準備匯入 Facebook 資料時發生內部錯誤。請重試;若問題持續發生,請聯絡支援團隊並提供時間戳記。
SY81085無法匯入 Facebook 粉絲專頁。請聯絡支援團隊並提供時間戳記。
SY81086地點建立作業遭業務規則拒絕。巢狀的 message 包含具體原因的代碼,例如帳戶的地點名額已用盡時,代碼為 SY10151。請讀取巢狀訊息;若為 SY10151,請加購地點或升級方案。
SY81087建立地點的請求失敗。請重試;若問題持續發生,請聯絡支援團隊並提供時間戳記。
SY81088地點建立作業因不明原因失敗。請聯絡支援團隊並提供時間戳記。
SY81089內部服務呼叫傳回非成功狀態。這不是您的請求所造成的問題。請重試 1 次;若問題持續發生,請聯絡支援團隊並提供時間戳記,以便我們追查內部呼叫。
SY81090內部地點建立呼叫期間發生非預期的錯誤。請重試;若問題持續發生,請聯絡支援團隊並提供時間戳記。

Social 代碼

SY950xx 範圍內的代碼來自 Social 端點:品牌、連線和社群貼文。與已連結帳號的代碼一樣,這些代碼會以巢狀結構出現在 HTTP 200 的回應主體中,因此即使狀態表示成功,也請讀取 data.<operation>.error(批次路由還須讀取 data.<operation>.errors)。

SY950xx Social codes

代碼含義處理方式
SY95041帳號已達品牌數量上限。API 方案不會出現此錯誤:該方案的品牌數量不限。API 方案無須處理。如果您看到此錯誤,請回報:GET /social/limits 應傳回 brands: null。
SY95042帳號已達目前計費週期的連線數量上限。系統會將上限與 GET /social/limits 中的 usage.connections 比較,這是計費數量:目前已連線的數量加上本期已釋出的數量。透過中斷連線 或封存品牌 釋出的名額會保留至週期結束,因此近期中斷連線不會消除此錯誤。請將您已釋出的其中一個帳號重新連結至原本的品牌(免費,會重複使用該名額)、再購買一組 5 個連線的加購套件(立即生效),或等待續約,屆時 usage.connectionsReleased 名額會恢復。將已釋出的帳號連結至其他品牌不會重複使用該名額。請參閱方案與加購項目。
SY95043此帳號中沒有該 ID 的品牌,或該品牌已封存。請從 GET /social/brands 重新讀取 ID。品牌 ID 是一般 UUID,不是 Base64 relay ID。
SY95044此帳號尚未啟用該平台。此帳號的 Social 方案不包含您要求連結的平台。請聯絡支援團隊,或選擇此帳號方案包含的平台。
SY95045此品牌沒有該平台的已連結頻道。請引導使用者透過該平台的連線連結 進行連結,或將該平台從 platforms 中移除。貼文排程後,若頻道中斷連線,也會出現此錯誤。
SY95046排程或時區無效。請傳送 scheduledAt 或 scheduleDate + scheduleTime,不可同時傳送兩者。scheduledAt 需要 UTC 時差;scheduleTime 為 HH:MM。時區使用 IANA 識別碼(tzCode)。
SY95047此帳號中沒有該 ID 的批次作業。請從批次建立 的回應中重新讀取 job.id。作業不會永久保留。
SY95048批次請求超過資料列數量上限。每個請求最多傳送 500 列,其餘資料請分成其他批次傳送。未建立任何項目。
SY95049重新導向 URL 無效。連線連結 中的 redirectUrl 和 errorUrl 必須是由您掌控的絕對 https URL。
SY95050批次驗證失敗;請查看各資料列的錯誤。未建立任何項目。請讀取 job.results[]:每個遭拒的資料列都包含從 0 開始計算的 index、該列的 clientReference,以及 errors[] 中的原因。請修正這些資料列,然後重新傳送整個批次。
SY95051品牌尚未符合建立滿 90 天的要求。品牌建立滿 90 天後才能封存。回應也會回報 status: "TENURE_NOT_MET",且未進行任何變更。請在第 90 天之後重試,屆時品牌及其連線會立即封存,但其連線名額仍會保留至計費週期結束。請參閱存續期間規則。
SY95052已連結的頻道不屬於此品牌。請將每個連線與建立該連線時所屬的品牌配對。此錯誤常見於使用一個品牌的貼文和另一個品牌的頻道 ID 來組成洞察資料請求。

SY95042 和 SY95044 是方案使用權限不足所導致的錯誤,不是輸入錯誤:若未變更方案就重試,仍會發生相同的錯誤。SY95045、SY95046、SY95049 和 SY95052 是輸入錯誤,可在下一個請求中修正。

Listings 使用權限代碼

Listings plan codes

代碼意義處理方式
SY10150此帳戶的地點數已達上限。封存一個地點、購買額外地點加購項目,或升級方案。請參閱方案與加購項目。
SY10151此帳戶已用完此方案的地點名額。如果使用沙箱單日通行證,表示其中的 2 個地點都已使用。處理方式與 SY10150 相同。如果使用單日通行證,請更新現有地點或選擇付費方案。從已連結帳戶的商家資訊建立地點時,此代碼也會以巢狀形式出現在 SY81086 中。
SY10152此地點的啟用時間尚未達到可封存的最低期限。地點必須持續啟用至帳戶規定的最短期間,預設為 90 天,POST /locations/archive 才會接受這些地點。請等待此期間結束。
SY10155此帳戶沒有 Listings 方案,因此無法建立地點。此 API 金鑰所屬的帳戶未訂閱 Listings,例如僅訂閱 Social 的帳戶。地點屬於 Listings 產品;請先訂閱此產品,再呼叫 POST /locations。

Listings scan 代碼

SY830xx 範圍內的代碼來自 listings scan 端點。無法建立掃描時,錯誤會以巢狀形式出現在 HTTP 200 的回應本文中:請讀取 data.createListingScan.errors,並確認 scan 為 null。SY83005 是例外:讀取不存在的掃描時,會傳回 404。

SY830xx listings scan codes

代碼意義處理方式
SY83001您的方案不提供 Listing scans。付費方案包含 Listings scans,沙箱單日通行證則不提供。請使用已訂閱付費方案的帳戶。請參閱方案與加購項目。
SY83002每月的 listing scan 配額已用完。訊息包含上限與重設時間,並會傳回 quota。請等到 quota.resetsAt,或聯絡我們以提高配額。重複執行過去 7 天內的掃描不會消耗配額,仍可執行。
SY83003欄位值無效。contextInfo 會在 field 下指出該欄位。請修正該欄位後重新傳送。phone 需要 6 至 15 位數字,countryIso 需要 2 個字母,而 stateIso 與 postalCode 在大多數國家都是必填欄位。
SY83004該國家不提供 Listing scans。請檢查 countryIso。訊息會指出遭拒的代碼。
SY83005找不到 Listing scan。會以 HTTP 404 傳回。此 ID 不存在、屬於其他帳戶,或掃描已超過 90 天而遭移除。請從 GET /listings/scans 讀取 ID。
SY83010Listing scans 暫時無法使用。掃描無法啟動時,也會以 failure 代碼傳回。請稍後重試。失敗的掃描不會消耗您的配額。

使用唯讀金鑰呼叫建立端點時,會改為收到 SY90016,其狀態為 HTTP 400。立即重試相同請求時,SY83001、SY83002 和 SY83004 不會改變,而 SY83010 則適合等待一段時間後重試。

rate_limited

429 Too Many Requests:此帳戶已超過其方案的速率限制。本文是標準錯誤回應,包含 retry_after_seconds 提示、可在支援請求中提供的 correlation_id,以及連回本節的 doc_url:

JSON
{  "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。您仍可開啟儀表板中的帳單頁面進行付款。

JSON
{  "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,後者會連結至本頁對應的章節。

JSON
{  "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 陣列:

Python
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 項檢查,先檢查狀態碼,再檢查回應酬載:

Python
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 主體內傳回錯誤酬載時引發例外。