Microsoft Web IQ 錯誤處理

所有 v3 API 都會回傳標準化錯誤回應，幫助你快速診斷和解決問題。本節涵蓋 HTTP 狀態碼、錯誤回應結構及常見故障排除情境。

Note

所有字串列舉值皆不區分大小寫。

HTTP 狀態代碼

狀態代碼	適用於	錯誤類別	Description	常見的原因
200	所有 API	Success	請求成功。	-
202	僅瀏覽	已接受	請求已接受處理（即時爬蟲）。	隨選爬行進行中
400	所有 API	錯誤的請求	請求參數無效。	缺少必填欄位、參數值無效、JSON 格式錯誤
401	所有 API	Unauthorized	驗證失敗或缺失。	API 金鑰無效，缺少 x-apikey 標頭
403	所有 API	禁止	有效的憑證，但權限不足。	API 金鑰缺乏所需權限
403	僅瀏覽	禁止	內容已過濾或網址被排除。	網址因政策或內容過濾而被封鎖
404	僅瀏覽	找不到	找不到文件。	網址無效或無法存取
410	所有 API	消失了	需要 HTTPS 認證。	請求是透過 HTTP 而非 HTTPS 進行的
415	所有 API	不支援媒體類型	內容類型不支援。	缺少或錯誤 `content-type` 的標頭
429	所有 API	過多要求	速率超過上限。	時間窗口內請求太多
430	僅瀏覽	伺服器錯誤	隨選爬蟲太多了。	過度的即時爬蟲請求
500	所有 API	內部伺服器錯誤	未預期的伺服器錯誤。	臨時伺服器問題

錯誤回應結構

所有錯誤回應皆遵循以下架構：

Field	類型	Description
`errorCode`	字串	更詳細的錯誤類別，有助於辨識錯誤類型。
`errorCategory`	字串	高階類別： `UserError` （用戶端/不可重試）或 `SystemError` （伺服器端/可重試）。
`userMessage`	字串	人類可以看懂的錯誤描述。
`technicalDetails`	字串 (選擇性)	除錯所需的額外技術資訊或參數驗證細節。
`retryAfter`	字串 (選擇性)	是時候等一等再重試了。
`requestId`	字串 (選擇性)	請求的唯一識別碼。
`traceId`	字串	分散式追蹤 ID 用於除錯與 Microsoft 支援。

Note

202 Accepted 回應（例如，瀏覽即時爬取輪詢）並非錯誤回應，且不使用上述錯誤結構。他們仍可能包含 retryAfter 一個數值，指示何時重試請求。

錯誤回應範例：

{
  "errorCode": "HandlerInvalidInput",
  "errorCategory": "UserError",
  "userMessage": "Invalid input provided. Please check your request parameters.",
  "technicalDetails": "Parameter validation failed: maxResults=100 exceeds maximum=50",
  "requestId": "req_abc123",
  "traceId": "trace_xyz789"
}

錯誤代碼參考

請求驗證錯誤

錯誤碼	HTTP 狀態	Category	Description
`RequestInvalidFormat`	400	`UserError`	JSON 主體或請求有效載荷結構異常。
`RequestInvalidMethod`	400	`UserError`	請求中指定的方法或工具名稱無效。
`HandlerInvalidInput`	400	`UserError`	輸入參數值無效（例如，空查詢、 `maxResults` 超出範圍 [1， 50]、列舉值無效）。
`RequestBlockedHeader`	400	`UserError`	請求包含一個區塊列入的除錯/變體標頭（例如， `X-Augmentations`， `X-DebugOptions`， `X-XapHostOverride`）。改用有文件記錄的 URL 參數（`?p1=`， `?debugoptions=`， `?atlahostname=`）來處理。
`RequestUnsupportedMediaType`	415	`UserError`	`content-type`標頭缺失或未`application/json`標示。
`MethodNotAllowed`	405	`UserError`	HTTP 方法不允許在路由中使用（例如，僅 POST 端點上的 GET）。

認證與授權錯誤

錯誤碼	HTTP 狀態	Category	Description
`AuthNoToken`	401	`UserError`	需要驗證。沒有提供持有憑證或 API 金鑰。
`AuthTokenParse`	401	`UserError`	認證令牌格式無效或令牌解析失敗。
`AuthInvalidApiKey`	401	`UserError`	所提供的 API 金鑰無效或無法被識別。
`AuthenticationFailed`	401	`UserError`	一般認證失敗。
`AuthExpiredTrial`	401	`UserError`	試用期已屆滿。請升級你的鑰匙。
`AuthMissingEntryId`	400	`UserError`	在請求情境中缺少應用程式識別碼/入口 ID。
`AuthAppIdSelectionRequired`	400	`UserError`	你的身份會對應到多個應用程式。使用 `APPID` 查詢參數指定目標應用程式。請參見呼叫多個 AppID。
`AuthUnauthorizedEntryId`	401	`UserError`	未經授權的入境證件。無法解析應用程式身份，或 `APPID` 是查詢參數在 API 金鑰認證下被傳送。
`AuthUnauthorizedAppId`	403	`UserError`	該指定 `APPID` 與您的身份無關。
`AuthUnauthorizedService`	403	`UserError`	來電者已取得認證，但未被授權存取所請求的服務/垂直領域。
`AuthBatchEndpointRequired`	403	`UserError`	應用程式必須使用批次端點（`X-FD-Batch: 1`）進行網頁搜尋。
`AuthMcpWebForbidden`	403	`UserError`	應用程式不得使用 MCP `web` 工具。
`AuthContentFormatForbidden`	403	`UserError`	此應用程式僅能存取段落。使用 `contentFormatpassage`。請參閱文章與內容格式。

速率限制誤差

錯誤碼	HTTP 狀態	Category	Description
`AuthUserThrottled`	429	`UserError`	請求頻率超過資源的速率限制。檢查 `retryAfter`。
`AuthUserDailyUsageExceeded`	429	`UserError`	每日請求配額已達標（UTC 00：00 重置）。檢查 `retryAfter`。

瀏覽 API 特定錯誤

錯誤碼	HTTP 狀態	Category	Description
`BrowseApiDocNotFound`	404	`UserError`	找不到文件。指定網址無內容。
`BrowseApiIsFilteredOut`	403	`UserError`	結果因政策或內容過濾而被刪除。
`BrowseApiIsUrlExcluded`	403	`UserError`	目標網址會被政策排除或禁止。
`BrowseApiTooManyOnDemandCrawls`	430	`UserError`	太多隨選即時爬取請求正在進行中。

服務與基礎設施錯誤

錯誤碼	HTTP 狀態	Category	可重試	Description
`InternalServerError`	500	`SystemError`	是的（30多歲）	內部伺服器錯誤。

常見錯誤情況

認證錯誤（401， 403）

症狀： 驗證失敗或禁止存取

解決方案：

確認你的 API 金鑰正確且標頭中包含 x-apikey 了
檢查你的 API 金鑰是否過期
確保你擁有該端點所需的權限
如果問題持續，請聯絡你的 Microsoft 代表

Example:

# Correct authentication
curl -X POST "https://api.microsoft.ai/v3/search/web" \
  -H "x-apikey: your-valid-key-here" \
  -H "content-type: application/json" \
  -d '{"query": "test"}'

速率限制（429）

症狀： 超過速率上限或每日配額用盡（AuthUserThrottled 或 AuthUserDailyUsageExceeded）

超出資源速率上限的請求回傳 HTTP 429。你的費率上限會顯示在 Web IQ 入口網站。

解決方案：

實作指數退避重試邏輯
等待錯誤回應的 retryAfter 間隔（例如 "60s"）後再嘗試
降低請求頻率
請注意，每日配額上限（AuthUserDailyUsageExceeded）將於 UTC 00：00 重置
如需申請更高額度，請聯絡 Web IQ 支援

範例回應：

{
  "errorCode": "AuthUserThrottled",
  "errorCategory": "UserError",
  "userMessage": "Rate limit exceeded. Please reduce your request frequency.",
  "retryAfter": "60s",
  "requestId": "req_123",
  "traceId": "trace_456"
}

參數無效（400）

症狀： 因參數無效而產生的錯誤請求

常見問題：

缺少必填欄位（例如參數 query ）
參數值超出範圍（例如， maxResults> 50）
無效參數型別（例如，字串取代整數）
不支援的參數值（例如，無效 contentFormat）

解決方案：

驗證所有必要參數的存在
將參數值與文件約束條件對照
確保正確的 JSON 格式

伺服器與基礎設施錯誤（500）

症狀： 意外的內部伺服器或上游服務錯誤（InternalServerError）

解決方案：

請檢查 retryAfter 欄位（預設為 "30s"），等待後再試一次請求
實作具指數退避與隨機抖動的重試機制
如果問題依舊，請聯絡 Microsoft 客服，並附上回覆中提供的資訊traceId

範例回應：

{
  "errorCode": "InternalServerError",
  "errorCategory": "SystemError",
  "userMessage": "The service is temporarily unavailable. Please try again later.",
  "technicalDetails": "An internal service error occurred. Please contact support if the issue persists.",
  "retryAfter": "30s",
  "traceId": "trace_456"
}

瀏覽 API 接受回應（202）

症狀： 已接受的回應與 retryAfter 場域

說明： 當 liveCrawl 設定為「備援」且需要爬取 URL 時，API 會回傳 202 已接受，並指示 retryAfter 何時重試請求。

處理：

# Initial request
curl -X POST "https://api.microsoft.ai/v3/browse" \
  -H "x-apikey: your-key" \
  -H "content-type: application/json" \
  -d '{"url": "https://example.com", "liveCrawl": "fallback"}'

# Response: 202 Accepted with retryAfter
# Wait for the specified time, then retry the same request

最佳做法

務必檢查狀態碼 ——不要假設成功
使用traceId作為支援 ——聯絡客服時請包含traceID
實作重試邏輯 - 對於暫態錯誤使用指數退避
處理 202 個回應 ——對於使用 Browse API 進行即時爬取，請等待並重試
發送前驗證 - 本地檢查參數以避免 400 錯誤
只使用 HTTPS - HTTP 請求會回傳 410 錯誤

意見反應

此頁面對您有幫助嗎？

上次更新時間： 2026-10-19

Microsoft Web IQ 錯誤處理

HTTP 狀態代碼

錯誤回應結構

錯誤代碼參考

請求驗證錯誤

認證與授權錯誤

速率限制誤差

瀏覽 API 特定錯誤

服務與基礎設施錯誤

常見錯誤情況

認證錯誤（401， 403）

速率限制（429）

參數無效（400）

伺服器與基礎設施錯誤（500）

瀏覽 API 接受回應 （202）

最佳做法

意見反應

其他資源

瀏覽 API 接受回應（202）