处理 REST API 错误

  • 项目

HTTP 错误响应分为两类：

  • 客户端错误 (400 代码级别) - 客户端发送了无效请求或请求不符合定义。
  • 服务器错误 (500 级别) – 服务器暂时无法完成请求或发生服务器错误。 再次尝试发送 HTTP 请求。

对任何Microsoft Defender for Endpoint API 的操作都可能返回下表中列出的错误代码。

  • 除错误代码外，每个错误响应还包含一条错误消息，可帮助解决问题。
  • 邮件是可以更改的自由文本。
  • 在页面底部，可以找到响应示例。

适用于：

希望体验 Defender for Endpoint？ 注册免费试用版。

错误代码 HTTP 状态代码 邮件
BadRequest BadRequest (400) 常规错误请求错误消息。
ODataError BadRequest (400) ) 指定特定错误 (OData URI 查询无效。
InvalidInput BadRequest (400) 无效输入 {无效输入}。
InvalidRequestBody BadRequest (400) 请求正文无效。
InvalidHashValue BadRequest (400) 哈希值 {无效哈希} 无效。
InvalidDomainName BadRequest (400) 域名 {无效域} 无效。
InvalidIpAddress BadRequest (400) IP 地址 {无效 IP} 无效。
InvalidUrl BadRequest (400) URL {无效 URL} 无效。
MaximumBatchSizeExceeded BadRequest (400) 超出最大批大小。 Received： {batch size received}， allowed： {batch size allowed}。
MissingRequiredParameter BadRequest (400) 缺少参数 {缺少参数}。
OsPlatformNotSupported BadRequest (400) 此操作不支持 OS 平台 {客户端 OS 平台}。
ClientVersionNotSupported BadRequest (400) 客户端版本 {supported client version} 及更高版本支持 {请求的操作}。
未经授权 (Unauthorized) 未经授权的 (401) 未经授权的 (授权标头) 无效或过期。
禁止访问 (Forbidden) 禁止 (403) 禁止 (有效令牌，但对操作) 权限不足。
DisabledFeature 禁止 (403) 未启用租户功能。
DisallowedOperation 禁止 (403) {不允许的操作和原因}。
NotFound 找不到 (404) “常规未找到”错误消息。
ResourceNotFound 找不到 (404) 找不到资源 {请求的资源}。
TooManyRequests 请求过多 (429) 响应表示按请求数或 CPU 达到配额限制。
InternalServerError 内部服务器错误 (500) (无错误消息，请重试操作。)

限制

当给定时间范围内 HTTP 请求数超过每个 API 允许的调用数时，HTTP 客户端可能会收到“请求过多错误 (429) ”。

HTTP 客户端应延迟重新提交进一步的 HTTPS 请求，然后以符合速率限制的方式提交请求。 响应标头中的 Retry-After，指示在发出新请求之前，) 等待 (以秒为单位的时间

忽略 429 响应或尝试在较短时间内重新提交 HTTP 请求会返回 429 错误代码。

正文参数区分大小写

提交的正文参数当前区分大小写。

如果遇到 InvalidRequestBody 或 MissingRequiredParameter 错误，可能是由错误的参数大写或小写字母引起的。

查看 API 文档页，检查提交的参数与相关示例匹配。

关联请求 ID

每个错误响应都包含用于跟踪的唯一 ID 参数。

此参数的属性名称为“target”。

就错误与我们联系时，附加此 ID 有助于查找问题的根本原因。

示例

{
    "error": {
        "code": "ResourceNotFound",
        "message": "Machine 123123123 was not found",
        "target": "43f4cb08-8fac-4b65-9db1-745c2ae65f3a"
    }
}

{
    "error": {
        "code": "InvalidRequestBody",
        "message": "Request body is incorrect",
        "target": "1fa66c0f-18bd-4133-b378-36d76f3a2ba0"
    }
}

提示

想要了解更多信息？ Engage技术社区中的 Microsoft 安全社区：Microsoft Defender for Endpoint技术社区。