Microsoft Web IQ 错误处理

所有 v3 API 都返回标准化的错误响应，帮助你快速诊断和解决问题。本部分介绍 HTTP 状态代码、错误响应结构和常见故障排除方案。

Note

所有字符串枚举值都区分大小写。

HTTP 状态代码

状态代码	应用到	错误类别	Description	常见原因
200	所有 API	成功	请求成功。	-
202	仅浏览	Accepted	已接受处理请求（实时爬网）。	“回退”时 `liveCrawl` 正在进行按需爬网
400	所有 API	错误的请求	无效的请求参数。	缺少必填字段、无效参数值、格式不正确的 JSON
401	所有 API	Unauthorized	身份验证失败或缺失。	API 密钥无效，缺少 x-apikey 标头
403	所有 API	禁止	有效凭据但权限不足。	API 密钥缺少所需的权限
403	仅浏览	禁止	已筛选的内容或排除的 URL。	受策略或筛选的内容阻止的 URL
404	仅浏览	未找到	找不到文档。	URL 无效或不可访问
410	所有 API	不存在 (Gone)	需要 HTTPS。	通过 HTTP 而不是 HTTPS 发出的请求
415	所有 API	不支持的媒体类型	不支持内容类型。	标头缺失或不正确`content-type`
429	所有 API	请求过多	超出速率限制。对于包含精细错误代码的浏览，在请求过多的按需爬网时也返回。	时间范围内请求过多或实时爬网请求过多
430	仅浏览	服务器错误	过多的按需爬网（旧错误代码）。	过多的实时爬网请求
500	所有 API	内部服务器错误	意外的服务器错误。	临时服务器问题
520	仅浏览	内容处理失败	检索了页面，但无法生成任何可用内容。	文档处理失败或超时，或动态呈现超时
523	仅浏览	已取消爬网	URL 不会生成任何内容，因为由于网站爬网配额有限，爬网未成功。	源主机的有限爬网配额
524	仅浏览	爬网超时	URL 未生成任何内容，因为爬网超时。	远程主机超时

状态 520、523 和 524 是默认启用的精细浏览错误代码的一部分。

错误响应结构

所有错误响应都遵循以下架构：

领域	类型	Description
`errorCode`	字符串	更详细的错误类别，可帮助识别错误类型。
`errorCategory`	字符串	高级类别： `UserError` （客户端/不可重试）或 `SystemError` （服务器端/可重试）。
`userMessage`	字符串	用户可读的错误说明。
`technicalDetails`	字符串（可选）	用于调试的其他技术信息或参数验证详细信息。
`retryAfter`	字符串（可选）	重试指南。对于`AuthUserThrottled`后`AuthUserDailyUsageExceeded`缀（例如，`"60s"`）的`InternalServerError`持续时间`"s"`。对于“浏览”粒度错误（包括 `TooManyOnDemandCrawls` （429），这是最早重试的 ISO 8601 UTC 时间戳（例如 `"2026-10-30T01:01:00Z"`）。未应用重试指南时省略。
`requestId`	字符串（可选）	请求的唯一标识符。
`traceId`	字符串	用于调试和Microsoft支持的分布式跟踪 ID。

Note

retryAfter 使用两种格式。 AuthUserThrottled和AuthUserDailyUsageExceededInternalServerError响应使用持续时间，例如"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`	未经授权的条目 ID。无法解析应用程序标识，或者 `APPID` 查询参数是使用 API 密钥身份验证发送的。
`AuthUnauthorizedAppId`	403	`UserError`	指定的 `APPID` 值与标识无关。
`AuthUnauthorizedService`	403	`UserError`	调用方已经过身份验证，但未经授权访问请求的服务/垂直。
`AuthBatchEndpointRequired`	403	`UserError`	应用程序需要使用批处理终结点（`X-FD-Batch: 1`）进行 Web 搜索。
`AuthMcpWebForbidden`	403	`UserError`	不允许应用程序使用 MCP `web` 工具。
`AuthContentFormatForbidden`	403	`UserError`	此应用程序仅有权访问段落。使用 `contentFormatpassage`。请参阅段落和内容格式。

速率限制错误

错误代码	HTTP 状态	Category	Description
`AuthUserThrottled`	429	`UserError`	请求频率超过 AppID 的速率限制。请检查 `retryAfter`。
`AuthUserDailyUsageExceeded`	429	`UserError`	已达到每日请求配额（重置时间为 00：00 UTC）。请检查 `retryAfter`。

浏览 API 特定错误

默认情况下，为“浏览”启用粒度错误代码。它们确定无法返回页面的特定原因，例如内容筛选、缺少的文档或爬网失败，并包括重试指南（如果适用）。无需选择加入或支持请求。

精细代码和旧代码使用标准错误响应结构。此处未列出的浏览错误将报告为 InternalServerError （HTTP 500）。

旧版浏览错误代码

这些代码在精细错误代码成为默认值之前使用。在处理较旧的响应时，会列出它们以供参考。

错误代码	HTTP 状态	Category	Description
`BrowseApiDocNotFound`	404	`UserError`	找不到文档。没有可用于指定 URL 的内容。
`BrowseApiIsFilteredOut`	403	`UserError`	结果已由内容策略、成人筛选、访问限制或域限制删除。
`BrowseApiIsUrlExcluded`	403	`UserError`	目标 URL 由 robots.txt 或爬网排除策略排除。
`BrowseApiTooManyOnDemandCrawls`	430	`UserError`	正在进行的按需实时爬网请求过多。降低实时爬网率。

精细浏览错误代码

错误代码	HTTP 状态	Category	典型 `retryAfter`	`userMessage`	建议的操作
`InvalidUrl`	400	`UserError`	省略	请求的 URL 无效。	在重试之前更正 URL。
`NotSupported`	400	`UserError`	省略	不支持请求的 URL。	使用指向支持的 Web 文档的 URL。
`URLFilteredOutSpamAdult`	403	`UserError`	大约 24 小时	请求的 URL 按垃圾邮件或成人策略进行筛选。	无法返回页面。不要先 `retryAfter`重试。
`URLFilteredOutEncumbrance`	403	`UserError`	大约 24 小时	请求的 URL 按内容限制进行筛选。	发布者或网站策略（如机器人指令或付费墙规则）不允许返回内容。不要先 `retryAfter`重试。
`URLFilteredOutSource403Forbidden`	403	`UserError`	大约 24 小时	源拒绝访问请求的 URL。	源站点返回了 HTTP 403。不要先 `retryAfter`重试。
`BrowseApiIsFilteredOut`	403	`UserError`	大约 24 小时，提供时	请求的 URL 已筛选掉。	当筛选页面的原因不再包含任何特定代码时返回。不要先 `retryAfter`重试。
`DocNotFound`	404	`UserError`	省略，除非由爬网服务提供	找不到请求的文档。	验证 URL，或设置为 `liveCrawl` “回退”以请求实时爬网。
`TooManyOnDemandCrawls`	429	`UserError`	爬网服务提供时	请求了太多按需爬网。	降低实时爬网率。如果 `retryAfter` 存在，请等待该时间再重试。
`FailedNoContent`	520	`SystemError`	大约 5 分钟	文档处理或发布无法生成可用内容。	重试后 `retryAfter`。
`DynamicRenderingTimeout`	520	`SystemError`	大约 5 分钟	动态页面呈现超时。	重试后 `retryAfter`，或重试而不 `renderDynamicPages`重试。
`ProcessingTimeout`	520	`SystemError`	大约 5 分钟	文档处理超时。	重试后 `retryAfter`。
`PolitenessCancellation`	523	`SystemError`	大约 5 分钟	已取消爬网以遵守源主机的爬网限制。	URL 不会生成任何内容，因为由于网站爬网配额有限，爬网未成功。重试后 `retryAfter`。
`HostCrawlTimeout`	524	`SystemError`	大约 5 分钟	源主机爬网超时。	URL 不会生成任何内容，因为爬网超时：远程主机没有及时响应。重试后 `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"，包括来自没有完整文档访问权限的应用程序的请求，其中“段落”是默认格式。请参阅浏览通道请求。

条件	错误代码	HTTP 状态	`userMessage`
`query` 缺少、空、仅空格或长度超过 1000 个字符	`HandlerInvalidInput`	400	提供的输入无效。请检查请求参数。
没有完整文档访问请求 `text`的应用程序， `html`或 `markdown`	`AuthContentFormatForbidden`	403	此应用程序仅有权访问段落。使用 contentFormat“passage”。

段落请求的所有其他浏览结果使用相同的状态代码和错误代码texthtml，以及markdown请求。这包括筛选的页面、未找到的文档、挂起的实时爬网（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）每天在 00：00 UTC 重置
若要请求更高的限制，请联系 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）

症状：响应正文中包含和urlretryAfter字段的已接受响应（202）

说明： 当 liveCrawl 索引中找不到“回退”且 URL 未找到时，API 可以异步启动爬网并返回 202 已接受。实时爬网受发布者礼貌限制和可用性的约束;“回退”不能保证实际爬网。相同的行为适用于每个 contentFormat行为，包括 passage。

处理：

检查 HTTP 状态 202。
从响应正文中读取 retryAfter 。它是最早重试的 ISO 8601 UTC 时间戳（例如 "2026-10-30T01:01:00Z"）。
等到那个时候。
再次发送相同的请求。该 url 字段包含要请求的 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 响应 - 对于使用实时爬网的浏览 API，请等待时间 retryAfter 并重试
处理这两retryAfter种格式 - 使用浏览 202 的持续时间AuthUserThrottledAuthUserDailyUsageExceededInternalServerError和 ISO 8601 时间戳以及粒度错误（包括 TooManyOnDemandCrawls （429）
发送之前进行验证 - 在本地检查参数以避免 400 错误
仅使用 HTTPS - HTTP 请求将返回 410 错误

反馈

此页面是否有帮助？

上次更新时间为 2026-11-01

Microsoft Web IQ 错误处理

HTTP 状态代码

错误响应结构

错误代码参考

请求验证错误

身份验证和授权错误

速率限制错误

浏览 API 特定错误

旧版浏览错误代码

精细浏览错误代码

浏览通道错误

服务与基础结构错误

常见错误场景

身份验证错误（401、403）

速率限制 （429）

无效参数 （400）

服务器和基础结构错误 （500）

浏览 API 接受的响应 （202）

最佳做法

反馈

其他资源

速率限制（429）

无效参数（400）

服务器和基础结构错误（500）

浏览 API 接受的响应（202）