错误

HTTP 代码

Access Worldpay API 遵循 RestfulAPI 原则，使用 HTTP 状态码来以符合标准的方式传递关于错误的信息。

在 4xx 范围内的状态码

这些代码表示请求存在问题，您必须加以解决。在解决问题之后，您可以安全地重试调用。

这类代码的常见示例是身份验证错误（HTTP 状态码 401）或请求正文验证错误（HTTP 状态码 400）。

在 5xx 范围内的状态码

这些代码一般表示连接的服务器侧有问题。这些问题的范围包括配置问题（可能针对具体商户或实体）到内部网络连接问题。这些问题可能是暂时的并且只会影响单个调用，也可能是长期的，会在很长一段时间内影响每个调用。通常，调用者无法自行解决这些问题。

5xx 错误最常见的示例是超时。

错误响应

随着 HTTP 状态码，Access Worldpay API 会在可行时返回一个标准化的响应正文，以便更详细地描述错误。

Access Worldpay API 的错误文档符合标准化 JSON 结构要求，其中包括：

• 顶层命名错误
• 描述性错误消息
• 可选用的更详细错误集合（如适用）
• 有助于识别错误的任何具体附加信息
• 在消息和名称中还包括了字段的 JSON 路径，让您能够将错误与请求正文中的具体值关联起来。这最常见于验证错误

错误名称表示错误的类型或类别。在 Access API 中，相同名称的错误具有相似的原因以及类似的解决方案。随着 API 集的发展，名称会被添加，或者不再使用。我们的目的是在整个 API 中一致地使用名称来表示相同的事物。在需要自动处理错误的情况下，HTTP 状态码和顶层名称是最可靠的决策依据。

错误消息旨在供人类而不是机器阅读，并且可能包含有关错误的有价值的上下文信息。它们不遵循特定的格式，也无法依赖其随着时间保持稳定。

通用错误格式

{
  "errorName": "errorName",
  "message": "human readable message"
}

特定错误格式

字段验证错误还必须包含：

示例

示例错误响应：

{
  "errorName": "bodyIsNotJson",
  "message": "You must provide valid json in the body of the request."
}

嵌套错误

包含字段验证的嵌套错误响应示例：

{
  "errorName": "bodyDoesNotMatchSchema",
  "message": "The json body provided does not match the expected schema",
  "validationErrors": [
    {
      "errorName": "fieldMustBeNumber",
      "message": "Field at path must be a number",
      "jsonPath": "$.amount"
    },
    {
      "errorName": "fieldIsMissing",
      "message": "Field at path must be present",
      "jsonPath": "$.description"
    },
    {
      "errorName": "fieldHasInvalidValue",
      "message": "Payment Instrument type must be card/wallet",
      "jsonPath": "$.paymentInstrument.type"
    }
  ]
}

标准错误

此列表并不全面，但涵盖了 Access 服务可能返回的主要错误类型。

顶层错误

字段验证错误