Errors

HTTP Codes

In line with our Restful API principles Access Worldpay APIs use HTTP status codes to deliver information about errors in a standards-compliant fashion.

Status codes in the 4xx range

These indicate a problem with the request which you must resolve. When you resolve the problem you can safely retry the call.

Common examples of these kinds of codes are authentication errors (HTTP status code 401) or request body validation errors (HTTP status code 400).

Status codes in the 5xx range

These typically indicate problems on the server side of the connection. These range from configuration problems (which could be specific to a merchant or entity) to internal network connectivity problems. They may be transient, only affecting a single call, or long-lasting, impacting every single call over a long period of time. Typically callers will not be able to resolve these issues on their own.

The most common example of 5xx errors are timeouts.

Error Responses

Alongside a HTTP status code, Access Worldpay APIs return a standardized response body describing the error in more detail wherever feasible.

Error documents from Access Worldpay APIs follow a standardized JSON structure, which include:

• a top-level named error
• a descriptive error message
• an optional collection of more detailed errors, if applicable
• any specific additional information which may help to identify the error
• the JSON Path to the field is also included with the message and name to enable you to associate an error with a specific value in the request body. This is most typical for validation errors

Error names indicate the type or class of error. Across Access APIs errors with the same name have similar causes and similar resolutions. As our API set grows names are added or may fall out of use. We aim to use names consistently across our APIs to represent the same things. Where automated processing of an error is required the HTTP status code and top level name are the most reliable elements to base decisions on.

Error messages are intended to be human readable rather than machine readable and may contain valuable contextual information about the error. They don't follow a specific format and can't be relied upon to remain stable over time.

Generic Error Format

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

Specific Error Formats

Field validation errors must also contain:

Examples

An example error response:

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

Nested Errors

An example of a nested error response that includes field validation:

{
  "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"
    }
  ]
}

Standard Errors

This list is not comprehensive but covers the major types of errors which Access services may return.

Top Level Errors

Field Validation Errors