API狀態碼與錯誤碼說明

本文檔列出 POST /serp/v1/request 介面可能回傳的所有狀態與錯誤資訊，便於您在呼叫介面時快速定位問題、完成除錯。

1. 通用約定

项	說明
請求路徑	POST /serp/v1/request
HTTP 狀態碼	業務成功與失敗均回傳 HTTP 200，請透過回應體中的 code 欄位判斷結果
請求 Content-Type	僅支援 application/x-www-form-urlencoded
驗證方式	請求標頭 Authorization: Bearer <api_key>

1.1 回應格式

所有回應統一為 JSON 結構：

情境	回應體範例
成功（isjson=1）	{"data":{"task_id":"...","result":...},"code":0}
成功（isjson≠1）	{"task_id":"...","data":...,"code":0}
失敗	{"data":"<錯誤描述>","code":<非0錯誤码>}（不回傳 task_id）

> 判定規則：code == 0 表示成功，其他值均為失敗；data 欄位為人类可读的錯誤描述。

---

2. 錯誤碼總覽

code	含義	一般分類
0	成功	—
400	請求參數錯誤 / 採集鏈路回傳錯誤	呼叫方需修正請求
401	鉴权失敗	API Key 問題
429	請求頻率超限	限流
504	採集服務逾時	服務端臨時異常，可重試
其他	下游採集服務透傳錯誤	視具體 data 內容判斷

---

3. 錯誤碼詳解

3.1 code: 401 — 鉴权失敗

API Key 缺失、格式錯誤、已過期或無效時回傳。

data 文字	含義	處理建議
apikey is empty!	請求未攜帶 Authorization 請求標頭	檢查請求標頭是否包含 Authorization: Bearer <api_key>
API key authentication failed：error-1	Authorization 標頭格式錯誤，未使用 Bearer <token> 形式	改為 Authorization: Bearer <api_key>
API key authentication failed：error-2	Bearer 後的 API Key 為空	在 Bearer 后填入有效的 API Key
API key authentication failed：error-3	驗證服務暫時不可用（缓存中為失敗态）	稍後重試，若持續出現請聯絡客服
API key authentication failed：error-4	鉴权服務請求失敗	稍後重試，若持續出現請聯絡客服
API key authentication failed：error-5	驗證服務回應異常	稍後重試，若持續出現請聯絡客服
API key authentication failed：error-6	API Key 無效（不存在或已被停用）	在使用者中心確認 API Key 是否正確、是否已被停用
Your API key has expired and is no longer valid.	API Key 已過期	續費或更換新的 API Key

3.2 code: 429 — 請求頻率超限

data 文字	含義	處理建議
Too Many Requests	呼叫頻率超過方案限制（預設每秒 10 次，高併發方案依所購上限）	降低併發請求頻率，或升級到更高 QPS 的方案

3.3 code: 400 — 請求格式錯誤

請求體格式不正確時回傳。

data 文字	含義	處理建議
JSON not supported!Please use form data!	Content-Type 錯誤使用了 application/json	改為 application/x-www-form-urlencoded 提交
Failed to parse form data!	表单資料解析失敗	檢查請求體是否為合法的 x-www-form-urlencoded 格式
Bad Request!	請求 Content-Type 不被支援（例如 multipart/form-data）	改用 application/x-www-form-urlencoded

3.4 code: 400 — 參數校验失敗

請求參數缺失、格式錯誤或互斥參數同時傳入時回傳。

通用參數

data 文字	觸發條件	處理建議
Missing query \q\ parameter	engine 為 google / bing / duckduckgo 時未傳 q	補充查詢關鍵字參數 q
Missing query \text\ parameter	engine=yandex 時未傳 text	補充查詢關鍵字參數 text
Invalid url format	engine=google_lens 时 url 非合法 http(s) 連結，也非合法 base64 圖片	使用合法的圖片 URL 或 base64 圖片字串
Invalid tbm parameter!	engine=google 时 tbm 參數取值不在支援清單內	參考引擎文件使用受支援的 tbm 值

Google Images

data 文字	觸發條件	處理建議
'period_unit'/'period_value' parameters can't be used with 'start_date'/'end_date' parameters.	時間範圍參數衝突	二選一：使用 period_unit/period_value，或使用 start_date/end_date

Google News

以下參數互斥，任意兩者同時傳入都會報錯：

data 文字	處理建議
topic_token, publication_token, and story_token parameters can't be used together.	三者只能傳一個
publication_token and story_token parameters can't be used together.	二選一
story_token and section_token parameters can't be used together.	二選一
topic_token and story_token parameters can't be used together.	二選一
topic_token and so parameters can't be used together.	二選一

Google Product

data 文字	觸發條件	處理建議
Missing query `product_id` parameter	未傳 product_id	补充 product_id
`product_id` is too short (minimum is 8 characters)	product_id 長度不足 8 位	使用完整的 product_id（≥ 8 位）
`product_id` query parameter cannot contain special characters	product_id 包含特殊字元	僅使用合法字元
offers, specs, and reviews parameters can't be used together	offers/specs/reviews 三者同時傳入	三選一

Google Flights

data 文字	觸發條件	處理建議
Missing query `departure_id` parameter	未傳出發地	补充 departure_id
Missing query `arrival_id` parameter	未傳目的地	补充 arrival_id

3.5 code: 400 — URL、地域與帳戶校驗

data 文字	含義	處理建議
url is invalid!: <具体原因>	URL 拼装或校验失敗，常见原因：url is required、invalid url format: ...、invalid base URL: ...	檢查传入的 URL 是否合法、是否使用受支援的引擎域名
url is invalid!	URL 網域規則未通過校驗	確認目標網域是否在支援範圍內
Not supported for use in mainland China:<ClientIP>	呼叫來源 IP 屬於中國大陸且未在白名單內	使用境外 IP 呼叫，或聯絡客服申請白名單
Package has expired!	方案已過期或可用餘額 ≤ 0	續費或升級方案

3.6 code: 504 — 採集服務逾時

data 文字	含義	處理建議
Data collection API request timeout!	下游採集服務網路異常或逾時	稍後重試；若持續出現請聯絡客服

3.7 code: 400 — 採集鏈路異常

請求參數本身合法，但採集執行鏈路回傳錯誤時使用。

data 文字	含義	處理建議
Parameter error	採集請求构造失敗（通常為 URL 解析失敗）	檢查传入參數是否合法，可重試一次
The data collection API returned incorrect parameters!	採集服務回傳了無法識別的結果	稍後重試；若持續出現請聯絡客服
Internal parsing error	採集结果内层資料解析失敗	稍後重試；若持續出現請聯絡客服
json value is not valid	json 參數取值不合法（僅支援 1、2、3、5）	修改為受支援的取值
JSON data retrieval failed	採集结果的 JSON 資料读取失敗	稍后重試
HTML data retrieval failed	採集结果的 HTML 資料读取失敗	稍后重試
HTML fetch failed: ... / JSON fetch failed: ...	json=2 时并发读取 HTML+JSON 失敗（可能為多条錯誤拼接）	稍后重試

3.8 其他 code — 下游透傳錯誤

當下游採集服務回傳非 200 狀態時，本介面會原樣透傳其 code 与錯誤描述。

欄位	來源
code	下游採集服務回傳的狀態碼
data	下游採集服務回傳的錯誤描述原文

> 此类錯誤的具体含義以下游採集服務的回傳為准。如长时间无法解决请聯絡客服并提供完整回應内容。

---

4. 回應範例

4.1 成功

{
  "data": { "task_id": "xxxx", "result": { "...": "..." } },
  "code": 0
}

4.2 參數錯誤

{
  "data": "Missing query `q` parameter",
  "code": 400
}

4.3 鉴权失敗

{
  "data": "API key authentication failed：error-6",
  "code": 401
}

4.4 API Key 已過期

{
  "data": "Your API key has expired and is no longer valid.",
  "code": 401
}

4.5 限流

{
  "data": "Too Many Requests",
  "code": 429
}

4.6 採集服務逾時

{
  "data": "Data collection API request timeout!",
  "code": 504
}

4.7 下游透傳錯誤

{
  "data": "下游回傳的具體錯誤資訊",
  "code": 500
}

---

5. 除錯速查

現象	优先檢查
一直回傳 code: 401	API Key 是否填寫正確、是否已過期、Authorization 头格式是否為 Bearer <api_key>
偶發 code: 429	是否超出方案 QPS 上限，建議增加重試間隔或升級方案
回傳 code: 400 且包含 Missing query	檢查必填业务參數是否齐全
回傳 code: 400 且包含 can't be used together	檢查是否同时传入了互斥參數
回傳 code: 504 或 code: 400 的採集链路文字	服務側臨時異常，稍後重試；持續出現請聯絡客服並提供 data 原文
回傳 Package has expired!	方案已過期或餘額不足，請續費
回傳 Not supported for use in mainland China	切換境外網路，或聯絡客服申請白名單

---

如遇到本文档未列出的錯誤信息，请将完整的請求參數与回應内容反馈给客服，以便快速定位問題。