Microsoft Web IQ 错误处理

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

Note

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

HTTP 状态代码

状态代码	应用到	错误类别	Description	常见原因
200	所有 API	成功	请求成功。	-
202	仅浏览	Accepted	已接受处理请求（实时爬网）。	正在进行的按需爬网
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	内部服务器错误	意外的服务器错误。	临时服务器问题

错误响应结构

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

领域	类型	Description
`errorCode`	字符串	更详细的错误类别，可帮助识别错误类型。
`errorCategory`	字符串	高级类别： `UserError` （客户端/不可重试）或 `SystemError` （服务器端/可重试）。
`userMessage`	字符串	用户可读的错误说明。
`technicalDetails`	字符串（可选）	用于调试的其他技术信息或参数验证详细信息。
`retryAfter`	字符串（可选）	重试前等待的时间。
`requestId`	字符串（可选）	请求的唯一标识符。
`traceId`	字符串	用于调试和Microsoft支持的分布式跟踪 ID。

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`	未经授权的条目 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`	请求频率超过资源的速率限制。请检查 `retryAfter`。
`AuthUserDailyUsageExceeded`	429	`UserError`	已达到每日请求配额（重置时间为 00：00 UTC）。请检查 `retryAfter`。

浏览 API 特定错误

错误代码	HTTP 状态	Category	Description
`BrowseApiDocNotFound`	404	`UserError`	找不到文档。没有可用于指定 URL 的内容。
`BrowseApiIsFilteredOut`	403	`UserError`	由于策略或内容筛选，结果已删除。
`BrowseApiIsUrlExcluded`	403	`UserError`	策略排除或禁止目标 URL。
`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）每天在 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）

症状： 包含 retryAfter 字段的已接受响应

说明： 当设置为“回退”并且需要爬网 URL 时 liveCrawl ，API 将返回 202 Accepted，该值 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 响应 - 对于使用实时爬网的浏览 API，请等待和重试
发送之前进行验证 - 在本地检查参数以避免 400 错误
仅使用 HTTPS - HTTP 请求将返回 410 错误

反馈

此页面是否有帮助？

上次更新时间为 2026-10-19

Microsoft Web IQ 错误处理

HTTP 状态代码

错误响应结构

错误代码参考

请求验证错误

身份验证和授权错误

速率限制错误

浏览 API 特定错误

服务与基础结构错误

常见错误场景

身份验证错误（401、403）

速率限制 （429）

无效参数 （400）

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

浏览 API 接受的响应 （202）

最佳做法

反馈

其他资源

速率限制（429）

无效参数（400）

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

浏览 API 接受的响应（202）