Microsoft Graph 错误响应和资源类型
使用标准 HTTP 状态代码和 JSON 错误响应对象返回 Microsoft Graph 中的错误。
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 格式。 如果请求由多个操作（例如批量或批处理操作）组成，则可能需要为每个操作返回独立的错误。 在这种情况下， 详细信息 列表将填充这些单独的错误。