> For the complete documentation index, see [llms.txt](https://docs.talordata.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.talordata.com/cn-tw/serp-api/api-status-codes-and-error-codes.md). # API狀態碼與錯誤碼說明 本文檔列出 `POST /serp/v1/request` 介面可能回傳的所有狀態與錯誤資訊，便於您在呼叫介面時快速定位問題、完成除錯。 ### 1. 通用約定 | 项 | 說明 | | --------------- | ---------------------------------------------- | | 請求路徑 | `POST /serp/v1/request` | | HTTP 狀態碼 | 業務成功與失敗**均回傳 HTTP 200**，請透過回應體中的 `code` 欄位判斷結果 | | 請求 Content-Type | 僅支援 `application/x-www-form-urlencoded` | | 驗證方式 | 請求標頭 `Authorization: Bearer ` | #### 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-1Authorization 標頭格式錯誤，未使用 Bearer <token> 形式改為 Authorization: Bearer <api_key>
API key authentication failed：error-2Bearer 後的 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-6API 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:` | 呼叫來源 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 ` | | 偶發 `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` | 切換境外網路，或聯絡客服申請白名單 | \--- 如遇到本文档未列出的錯誤信息，请将完整的請求參數与回應内容反馈给客服，以便快速定位問題。