Microsoft Graph 错误响应和资源类型

项目
08/24/2023

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

HTTP 状态代码

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

状态代码	状态消息	说明
400	错误的请求 (Bad Request)	无法处理请求，因为格式有误或者不正确。
401	未经授权 (Unauthorized)	资源所需的身份验证信息缺少或无效。
402	需要付款	尚未满足 API 的付款要求。
403	禁止访问	对于请求的资源，访问被拒绝。用户可能没有足够的权限或可能没有所需的许可证。重要：如果条件访问策略应用于资源，可能会返回一 `HTTP 403; Forbidden error=insufficient_claims` 条消息。有关 Microsoft Graph 和条件访问的更多详细信息，请参阅 Azure Active Directory 条件访问的开发人员指南。
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 格式。如果请求由多个操作（例如批量或批处理操作）组成，则可能需要为每个操作返回独立的错误。在这种情况下， 详细信息 列表将填充这些单独的错误。

Microsoft Graph 错误响应和资源类型

HTTP 状态代码

错误的资源类型

JSON 表示形式

属性

其他资源

其他资源