Microsoft Web IQ 錯誤處理

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

v1 客戶管理 API 使用獨立 的授權資源狀態 、 範圍管理狀態碼與錯誤實體。

Note

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

HTTP 狀態代碼

狀態代碼 適用於 錯誤類別 Description 常見的原因
200 所有 API Success 請求成功。 -
202 僅瀏覽 已接受 請求已接受處理(即時爬蟲)。 當「備用」時,隨選爬行正在進行 liveCrawl 中
400 所有 API 錯誤的請求 請求參數無效。 缺少必填欄位、參數值無效、JSON 格式錯誤
401 所有 API Unauthorized 驗證失敗或缺失。 API 金鑰無效,缺少 x-apikey 標頭
403 所有 API 禁止 有效的憑證,但權限不足。 API 金鑰缺乏所需權限
403 僅瀏覽 禁止 內容已過濾或網址被排除。 網址因政策或內容過濾而被封鎖
404 所有 API 找不到 找不到路徑。 拼字錯誤或不支援的端點路徑
404 僅瀏覽 找不到 找不到文件。 網址無效或無法存取
410 所有 API 消失了 需要 HTTPS 認證。 請求是透過 HTTP 而非 HTTPS 進行的
415 所有 API 不支援媒體類型 內容類型不支援。 缺少或錯誤 content-type 的標頭
429 所有 API 過多要求 速率超過上限。 對於 Browse 則帶有細緻錯誤碼,當需求過多的按需爬取時也會回傳。 時間窗口內請求過多,或是過多的即時爬取請求
430 僅瀏覽 伺服器錯誤 太多隨選爬蟲(舊有錯誤代碼)。 過度的即時爬蟲請求
500 所有 API 內部伺服器錯誤 未預期的伺服器錯誤。 臨時伺服器問題
520 僅瀏覽 內容處理失敗 該頁面被檢索,但無法產生可用的內容。 文件處理失敗或逾時,或動態渲染逾時
523 僅瀏覽 爬行取消 由於網站爬取配額有限,該網址無法產生任何內容。 原始主機的有限爬取配額
524 僅瀏覽 爬行暫停 網址沒有產生任何內容,因為爬取已經逾時了。 遠端主機超時了

狀態 520、523 和 524 是細 緻的瀏覽錯誤代碼,預設為啟用。

錯誤回應結構

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

Field 類型 Description
errorCode 字串 更詳細的錯誤類別,有助於辨識錯誤類型。
errorCategory 字串 高階類別: UserError (用戶端/不可重試)或 SystemError (伺服器端/可重試)。
userMessage 字串 人類可以看懂的錯誤描述。
technicalDetails 字串 (選擇性) 除錯所需的額外技術資訊或參數驗證細節。
retryAfter 字串 (選擇性) 重試指引。 對於 、 、 和 ,一個帶有"s"後綴的持續時間(例如,"60s")。ScopeFailedToApplyInternalServerErrorAuthUserDailyUsageExceededAuthUserThrottled 對於瀏覽的細緻錯誤,包括 TooManyOnDemandCrawls (429),ISO 8601 UTC 時間戳記(例如 "2026-10-30T01:01:00Z"),這是最早重試的時間。 當無重試指引適用時,則會省略。
requestId 字串 (選擇性) 請求的唯一識別碼。
traceId 字串 分散式追蹤 ID 用於除錯與 Microsoft 支援。

Note

retryAfter 使用兩種格式。 AuthUserThrottled、、 AuthUserDailyUsageExceeded、 InternalServerError,且 ScopeFailedToApply 回應使用如 "60s"的持續時間。 瀏覽 202 Accepted 回應與瀏覽細分錯誤則使用絕對的 ISO 8601 UTC 時間戳記,例如 "2026-10-30T01:01:00Z"。 僅靠 HTTP 狀態並不決定格式: TooManyOnDemandCrawls 回傳 429,但會使用時間戳記。 重試邏輯應該能同時處理兩種格式。

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]、列舉值無效)。 對於瀏覽段落請求, query 缺少、空白或超過1000字元。
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 請求頻率超過你的 AppID 速率限制。 檢查 retryAfter。
AuthUserDailyUsageExceeded 429 UserError 每日請求配額已達標(UTC 00:00 重置)。 檢查 retryAfter。

命名範圍錯誤

當 scopeName 提供時, failOnMissingScope 預設為 true,包括省略或 null。 若服務回報無法套用所需的範圍,網頁搜尋、新聞搜尋與自動會在公開 REST 回應中回傳以下 HTTP 狀態 errorCode :

條件 錯誤代碼 HTTP 狀態 Action
範圍查詢確認該命名範圍不見了。 HandlerInvalidInput 400 請檢查名稱、所選 Web IQ AppID 的帳單帳號,以及新範圍是否已傳播。
該範圍不能用於其他原因,包括回收失敗或未知原因。 ScopeFailedToApply 500 依照回應的重試指引進行有界退後;如果失敗持續,請聯絡客服。 不要以為範圍名稱無效。

在傳播過程中,處理請求的分割區或副本可能會缺少新建立的範圍。 如果您的應用程式需要有範圍的結果,請不要僅為繞過錯誤而更改:failOnMissingScope: falsefalse允許搜尋整個索引而不使用範圍。

當 時 false,回報的失敗申請會如 scopeApplied: false 一般搜尋回應般回傳。 成功申請的報告為 scopeApplied: true;零匹配文件不代表範圍-應用失敗。 若未報告申請結果,該欄位會被省略。 沒有 scopeName, failOnMissingScope 則沒有影響。

也不scopeApplied: truefailOnMissingScope: true保證使用最新的定義。 請參閱 範圍驗證與推廣。

瀏覽 API 特定錯誤

瀏覽時預設啟用細緻錯誤碼。 它們會明確指出頁面無法回傳的具體原因,例如內容過濾、文件遺失或爬取失敗,並在適用時附上重試指引。 不需要主動加入或請求支援。

細緻碼與舊有碼則使用標準 錯誤響應結構。 未在此列出的瀏覽錯誤會被報告為 InternalServerError (HTTP 500)。

舊版瀏覽錯誤代碼

這些代碼在細分錯誤碼成為預設之前就已使用。 處理舊回覆時會列出這些資訊作為參考。

錯誤碼 HTTP 狀態 Category Description
BrowseApiDocNotFound 404 UserError 找不到文件。 指定網址無內容。
BrowseApiIsFilteredOut 403 UserError 結果因內容政策、成人過濾、存取限制或網域限制而被取消。
BrowseApiIsUrlExcluded 403 UserError 目標網址會被 robots.txt 或爬取的排除政策排除。
BrowseApiTooManyOnDemandCrawls 430 UserError 太多隨選即時爬取請求正在進行中。 降低即時爬行率。

細緻瀏覽錯誤碼

錯誤碼 HTTP 狀態 Category 典型 retryAfter userMessage 建議的動作
InvalidUrl 400 UserError 省略 所請求的網址無效。 重試前請先修正網址。
NotSupported 400 UserError 省略 所請求的網址不被支援。 使用指向支援網頁文件的網址。
URLFilteredOutSpamAdult 403 UserError 大約24小時 所請求的網址已被垃圾郵件或成人政策過濾。 頁面無法退回。 之前不要重試 retryAfter。
URLFilteredOutEncumbrance 403 UserError 大約24小時 所請求的網址已依內容限制進行過濾。 出版商或網站的政策,例如機器人指令或付費牆規則,不允許內容被退還。 之前不要重試 retryAfter。
URLFilteredOutSource403Forbidden 403 UserError 大約24小時 該來源拒絕存取所要求的網址。 來源網站回傳 HTTP 403。 之前不要重試 retryAfter。
BrowseApiIsFilteredOut 403 UserError 供應時約24小時 所請求的網址已被過濾掉。 當頁面因某些原因被篩選時,該頁面會回傳,而該原因沒有更具體的程式碼說明。 之前不要重試 retryAfter。
DocNotFound 404 UserError 除非爬行服務提供,否則省略 但未找到所需文件。 請確認網址,或設定 liveCrawl 為「備用」以請求即時爬取。
TooManyOnDemandCrawls 429 UserError 由爬行服務供應時 要求的隨選爬蟲太多了。 降低即時爬行率。 如果 retryAfter 存在,請等到那個時間再重試。
FailedNoContent 520 SystemError 大約五分鐘 文件處理或發布無法產生可用的內容。 之後 retryAfter再試一次。
DynamicRenderingTimeout 520 SystemError 大約五分鐘 動態頁面渲染逾時。 在 之後 retryAfter重試,或不 renderDynamicPages嘗試。
ProcessingTimeout 520 SystemError 大約五分鐘 文件處理時間過時。 之後 retryAfter再試一次。
PolitenessCancellation 523 SystemError 大約五分鐘 為了尊重來源主機的爬行限制,爬行被取消。 由於網站爬取配額有限,該網址無法產生任何內容。 之後 retryAfter再試一次。
HostCrawlTimeout 524 SystemError 大約五分鐘 來源主機爬行超時。 網址沒有產生任何內容,因為爬取時間過時:遠端主機沒有及時回應。 之後 retryAfter再試一次。

當有重試延遲時,回應會以 ISO 8601 UTC 時間戳yyyy-MM-ddTHH:mm:ssZ記的形式以retryAfter格式 ,例如 "retryAfter": "2026-10-30T01:01:00Z"。 在那之前不要重試。 若 retryAfter 未執行,則不適用重試指引。

細緻錯誤回應範例:

{
  "errorCode": "URLFilteredOutEncumbrance",
  "errorCategory": "UserError",
  "userMessage": "The requested URL was filtered by content restrictions.",
  "retryAfter": "2026-10-31T01:00:00Z",
  "traceId": "0123456789abcdef0123456789abcdef"
}

瀏覽文章錯誤

這些錯誤適用於具有 contentFormat: "passage"的瀏覽請求,包括來自未完全存取文件的應用程式的請求,該應用程式預設格式為「passage」。 請參見 瀏覽文章請求。

條件 錯誤碼 HTTP 狀態 userMessage
query 缺少、空白、僅留白,或超過1000字元 HandlerInvalidInput 400 輸入無效。 請檢查您的請求參數。
沒有完整文件存取請求text的應用程式,或 htmlmarkdown AuthContentFormatForbidden 403 此應用程式僅能存取段落。 使用 contentFormat 的「passage」。

所有其他瀏覽結果用於通過請求,使用與 、 htmlmarkdown 及請求相同的狀態碼與錯誤碼text。 這包括篩選頁面、找不到文件、待進行的即時爬取(202 Accepted),以及爬取失敗。

服務與基礎設施錯誤

錯誤碼 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)

超出 AppID 速率限制的請求會回傳 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)

症狀:接受回應(202)中,響應主體中欄位url為retryAfter

說明: 當 liveCrawl 是「備用」且 URL 未在索引中找到時,API 可以非同步啟動爬取並回傳 202 已接受。 即時爬蟲會受到出版商禮貌限制及可用性的限制;「備用」並不保證真的會爬行。 相同的行為適用於所有 contentFormat,包括 passage。

處理:

  1. 檢查 HTTP 狀態 202。
  2. 請閱讀 retryAfter 回應正文。 這是 ISO 8601 UTC 時間戳記(例如), "2026-10-30T01:01:00Z"是最早可以重試的時間。
  3. 等到那時候。
  4. 再寄一次同樣的請求。 欄位包含 url 要請求的網址;預設是你請求的 URL。
  5. 限制投票嘗試次數。 無法完成的爬行最終會回傳錯誤,例如 HostCrawlTimeout (524) 或 FailedNoContent (520)。
# 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", "contentFormat": "passage", "query": "information about this domain", "liveCrawl": "fallback"}'

# Example response when the URL isn't indexed: 202 Accepted with "retryAfter": "2026-10-30T01:01:00Z"
# Wait until that time, then send the same request again

最佳做法

  1. 務必檢查狀態碼 ——不要假設成功
  2. 使用traceId作為支援 ——聯絡客服時請包含traceID
  3. 實作重試邏輯 - 對於暫態錯誤使用指數退避
  4. 處理 202 個回應 - 對於使用 Browse API 進行即時爬取,請等到時間到時 retryAfter 再重試
  5. 同時處理兩種retryAfter格式——使用AuthUserThrottled瀏覽 、 AuthUserDailyUsageExceeded、 InternalServerErrorScopeFailedToApply、 的時間戳,以及 ISO 8601 時間戳記來處理瀏覽 202 和細緻錯誤,包括 TooManyOnDemandCrawls (429)
  6. 發送前驗證 - 本地檢查參數以避免 400 錯誤
  7. 只使用 HTTPS - HTTP 請求會回傳 410 錯誤