所有 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。
處理:
- 檢查 HTTP 狀態 202。
- 請閱讀
retryAfter回應正文。 這是 ISO 8601 UTC 時間戳記(例如),"2026-10-30T01:01:00Z"是最早可以重試的時間。 - 等到那時候。
- 再寄一次同樣的請求。 欄位包含
url要請求的網址;預設是你請求的 URL。 - 限制投票嘗試次數。 無法完成的爬行最終會回傳錯誤,例如
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
最佳做法
- 務必檢查狀態碼 ——不要假設成功
- 使用traceId作為支援 ——聯絡客服時請包含traceID
- 實作重試邏輯 - 對於暫態錯誤使用指數退避
-
處理 202 個回應 - 對於使用 Browse API 進行即時爬取,請等到時間到時
retryAfter再重試 -
同時處理兩種
retryAfter格式——使用AuthUserThrottled瀏覽 、AuthUserDailyUsageExceeded、InternalServerErrorScopeFailedToApply、 的時間戳,以及 ISO 8601 時間戳記來處理瀏覽 202 和細緻錯誤,包括TooManyOnDemandCrawls(429) - 發送前驗證 - 本地檢查參數以避免 400 錯誤
- 只使用 HTTPS - HTTP 請求會回傳 410 錯誤