错误是使用 API 时开发者体验中至关重要的一部分。开发者在学习 API 的过程中不可避免地会遇到错误。返回给他们的错误消息的质量和一致性将在他们学习 API 的速度、他们使用 API 的效率以及他们使用 API 的乐趣方面发挥重要作用。
本文档描述了 OpenStack 中一个新兴的标准，用于提供结构化的错误响应，这些响应可以一致地处理，并包含编码，最终允许通过该字段的值在网络和文档中搜索错误。代码即使返回相同的 HTTP 状态码，这些代码也有助于区分对相同 HTTP 方法和 URI 的不同错误的根本原因。
注意
选择添加这些结构化错误响应的服务建议，这样做不被视为向后不兼容的更改，并鼓励他们添加这些响应，而无需对服务进行版本控制。但是，当一个代码被添加到特定响应中时，对该响应的该代码的后续更改是不兼容的更改。
本文档中“MUST”（必须）、“MUST NOT”（禁止）、“REQUIRED”（必需）、“SHALL”（应）、“SHALL NOT”（不应）、“SHOULD”（应该）、“SHOULD NOT”（不应）、“RECOMMENDED”（推荐）、“MAY”（可以）和“OPTIONAL”（可选）等关键词应按照 RFC 2119 中所述进行解释。
{
"$schema": "https://schema.json.js.cn/draft-04/schema#",
"id": "https://specs.openstack.org/openstack/api-wg/errors-schema.json#",
"type": "object",
"properties": {
"errors": {
"type": "array",
"description": "An ordered list of errors with the most recent error first.",
"minItems": 1,
"items": {
"type": "object",
"description": "Additional information about problems encountered while performing an operation.",
"properties": {
"request_id": {
"type": "string",
"description": "A unique identifier for this particular occurrence of the problem. If this property is present, it MUST match the X-Openstack-Request-Id header of the response in which it occurred."
},
"code": {
"type": "string",
"pattern": "^[a-z0-9._-]+$",
"description": "A service-specific error code. The general form of the code is service-type.error-code. service-type MUST be the service type as defined by the service types authority at https://specs.openstack.org/openstack/service-types-authority. error-code is defined by service project team and MUST only consist of lowercase alpha, numeric, '.', '_', and '-' characters."
},
"status": {
"type": "integer",
"description": "The HTTP status code applicable to this problem. It MUST match the status code of the response in which it occurred."
},
"title": {
"type": "string",
"description": "A short, human-readable summary of the problem. It SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization."
},
"detail": {
"type": "string",
"description": "A human-readable explanation specific to this occurrence of the problem."
},
"links": {
"type": "array",
"description": "An array that MUST contain at least one Link Description Object with a 'rel': 'help' and an 'href' that links to a resource that can help the user as defined by https://specs.openstack.org/openstack/api-wg/guidelines/errors.html#errors-documentation",
"minItems": 1,
"items": { "$ref": "https://schema.json.js.cn/draft-04/links" }
}
},
"required": [
"code",
"status",
"title",
"detail",
"links"
]
}
}
},
"required": [
"errors"
]
}
{
"errors": [
{
"request_id": "1dc92f06-8ede-4fb4-8921-b507601fb59d",
"code": "orchestration.create_failed",
"status": 418,
"title": "The Stack could not be created",
"detail": "The Stack could not be created because of error(s) in other parts of the system.",
"links": [
{
"rel": "help",
"href": "https://developer.openstack.org/api-ref/orchestration/errors/orchestration.create-failed"
}
]
},
{
"request_id": "d413ea12-dfcd-4009-8fad-229b475709f2",
"code": "compute.scheduler.no-valid-host-found",
"status": 403,
"title": "No valid host found",
"detail": "No valid host found for flavor m1.xlarge.",
"links": [
{
"rel": "help",
"href": "https://developer.openstack.org/api-ref/compute/errors/compute.scheduler.no-valid-host-found"
}
]
}
]
}
注意
这个示例完全是虚构的。这不是 Orchestration 或 Compute 返回错误的方式。它仅仅说明了服务如何将错误链接在一起。示例 hrefs 在links只是示例，但表明服务应该负责发布和维护与其生成的错误代码相关的文档。
的意图是代码有两个方面
为了满足这两个要求，用于错误代码的字符串需要是自描述且人类可读的，同时也要彼此区分。建议避免缩写。
例如，考虑一个提供 URI 的服务，/servers/{uuid}。至少有两种不同的方式，当对该 URI 发出404 Not Found响应时会发生。一种是当前不存在具有GET{uuid}的服务器。另一种是 URI 已输入不正确（例如，/server/{uuid}）。这些条件应导致不同的代码。这两种情况的两个可能代码是compute.server.not_foundcompute.uri.not_found和，分别。错误 JSON Schema