处理 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技术社区。