Microsoft Graph 错误响应和资源类型

Microsoft Graph 中的错误使用标准 HTTP 状态代码和 JSON 错误响应对象返回。

HTTP 状态代码

下表列出并描述可以返回的 HTTP 状态代码。

状态代码 状态消息 说明
400 错误的请求 (Bad Request) 无法处理请求,因为它格式不正确或不正确。
401 未经授权 (Unauthorized) 资源所需的身份验证信息缺少或无效。
402 需要付款 尚未满足 API 的 付款要求
403 禁止访问 对于请求的资源,访问被拒绝。 用户可能没有足够的权限或可能没有所需的许可证。

重要: 如果条件访问策略应用于资源,可能会返回一 HTTP 403; Forbidden error=insufficient_claims 条消息。 有关 Microsoft Graph 和条件访问的详细信息,请参阅Microsoft Entra条件访问的开发人员指南
404 未找到 (Not Found) 所请求的资源不存在。
405 方法不允许 (Method Not Allowed) 资源上不允许使用请求中的 HTTP 方法。
406 不接受 (Not Acceptable) 该服务不支持“Accept”标头中请求的格式。
409 Conflict 当前状态与请求预期的状态的冲突。 例如,指定的父文件夹可能不存在。
410 不存在 (Gone) 所请求的资源在服务器不再可用。
411 需要长度 (Length Required) 请求上需要 Content-Length 标头。
412 前提条件不满足 (Precondition Failed) 请求中提供的前置条件 (例如 if-match 标头) 与资源的当前状态不匹配。
413 请求实体太大 (Request Entity Too Large) 请求的大小超出最大限制。
415 媒体类型不受支持 (Unsupported Media Type) 请求的内容类型是服务不支持的格式。
416 请求的范围不满足 (Requested Range Not Satisfiable) 指定的字节范围无效或不可用。
422 实体无法处理 (Unprocessable Entity) 无法处理请求,因为它在语义上不正确。
423 已锁定 正在访问的资源被锁定。
429 请求过多 (Too Many Requests) 客户端应用程序已受到限制,在经过一段时间后,不应尝试重复请求。
500 内部服务器错误 (Internal Server Error) 处理请求时出现内部服务器错误。
501 未实现 (Not Implemented) 所请求的功能未实现。
503 服务不可用 服务暂时无法维护或过载。 你可以在延迟后重复该请求,其长度可以在 Retry-After 标头中指定。
504 网关超时 服务器在充当代理时,未收到来自尝试完成请求所需的上游服务器的及时响应。
507 存储不足 (Insufficient Storage) 已达到最大存储配额。
509 超出带宽限制 您的应用因超出最大带宽上限而被限制。 应用可以在等待一段时间之后再重试该请求。

错误响应是单个 JSON 对象,包含名为“error”的单个属性。 此对象包括错误的所有详细信息。 除了 HTTP 状态代码外,还可以使用此处返回的信息,或者使用此信息替代 HTTP 状态代码。 以下是完整的 JSON 错误正文示例。

{
  "error": {
    "code": "badRequest",
    "message": "Uploaded fragment overlaps with existing data.",
    "innerError": {
      "code": "invalidRange",
      "request-id": "request-id",
      "date": "date-time"
    }
  }
}

错误的资源类型

只要处理请求的过程中出现错误,就会返回错误资源。

错误响应遵循 Microsoft REST API 指南中的定义。

JSON 表示形式

错误资源由单个资源组成:

{
  "error": {
    "code": "string",
    "message": "string",
    "innererror": { 
      "code": "string"
    },
    "details": []
  }
}
属性名称 说明
code string 发生的错误的错误代码字符串
message string 有关发生的错误的开发人员就绪消息。 不应直接向用户显示此内容。
innererror 错误对象 可选。 可能比顶级错误更具体的附加错误对象。
details error object 可选。 其他错误对象的列表,这些对象可能会提供处理请求时遇到的多个错误的明细。

属性

代码属性包含可在代码中依赖的计算机可读值。

innererror 对象可能会递归地包含更多具有其他更具体的错误代码属性的 innererror 对象。 处理错误时,应用应循环访问所有可用的嵌套错误代码,并使用他们理解的最详细的错误代码。

message 属性是描述错误条件的可读值。 不要依赖于代码中此值的内容。

根目录中 的 message 属性包含供开发人员读取的错误消息。 错误消息未本地化,不应直接向用户显示。 处理错误时,代码不应依赖于 消息 属性值,因为它们可以随时更改,并且通常包含特定于失败请求的动态信息。 应仅针对代码属性中返回的错误代码 进行编码

details 属性是错误对象的可选数组,这些对象与顶级错误对象具有相同的 JSON 格式。 如果请求由多个操作(例如批量或批处理操作)组成,则可能需要为每个操作返回独立的错误。 在这种情况下, 详细信息 列表将填充这些单独的错误。