Last Updated: 09 May 2024 | Change Log

Errors

Firewall settings

Your firewall must allow inbound and outboud traffic from us. If you are unable to access our API, please speak to your webhosting team to whitelist our domains:

  • https://try.access.worldpay.com/ and
  • https://access.worldpay.com/

Please ensure you use DNS whitelisting and not explicit IP whitelisting.

HTTP Codes

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.

Info
The API reference for specific API calls details some specific error names which you can see, although the list is not exhaustive.

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"
}
FieldTypeDescription
errorNameStringA machine and human readable error type for clarity and semantic understanding of the error.
messageStringA human readable message giving a corrective action for the error. This is not for machine consumption.

Specific Error Formats

Field validation errors must also contain:

Additional FieldTypeDescription
jsonPathStringThis field represents the JSONPath of the element within the request body associated with the error.

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

Error NameHTTP CodeDescriptionAdditional Fields
headerIsMissing400A header in the request is missing. This header is a mandatory element of the request. The name of the header is in the headerName field.headerName: String
headerHasInvalidValue400, 406, 415A header in the request does not contain an expected value. This header must contain one of the expected valid values.headerName: String
bodyIsEmpty400The body within the request is empty. A body is required to be non-empty.
bodyIsNotJson400The body within the request is not valid json. This body is required to be valid json.
bodyDoesNotMatchSchema400There were field validation errors. The errors that occurred are within the validationErrors array.validationErrors: Array of field validation errors
urlContainsInvalidValue400The URL contains a value or values that are invalid.validationErrors: Array of url path or query parameter validation errors.
entityIsNotConfigured400The provided merchant entity (while valid as input) is not configured for use.
paymentInstrumentIsNotSupported400The payment instrument (while valid as input) is not configured for the given merchant entity
underlyingPaymentInstrumentHasExpired400Underlying payment instrument has expired when its details are not provided in the request
currencyIsNotSupported400The currency (while it is a valid currency) is not configured for use by the given merchant entity
internalErrorOccurred500An error occurred within the service (potentially due to an interaction with a downstream service).
serviceUnavailable503Service cannot fulfil the request even though service functions without internal errors

Field Validation Errors

Error NameDescription
fieldIsMissingThe identified field is missing. This field is a mandatory element of the request body.
fieldMustBeStringThe identified field is not the correct type. This field is required to be a string.
fieldMustBeNumberThe identified field is not the correct type. This field is required to be a number.
fieldMustBeIntegerThe identified field is not the correct type. This field is required to be an integer.
fieldMustBeBooleanThe identified field is not the correct type. This field is required to be a boolean.
fieldMustBeObjectThe identified field is not the correct type. This field is required to be a JSON object.
fieldMustBeArrayThe identified field is not the correct type. This field is required to be an array.
fieldIsNullThe identified field is null. This field is a mandatory element of the request body.
fieldIsEmptyThe identified field is empty. This field is required to be non-empty.
fieldHasInvalidValueThe identified field does not contain an expected value. This field must contain one of the expected valid values.
fieldIsNotAllowedThe identified field is present when it is explicitly not allowed in the request.
numberIsTooSmallThe identified field contains a number that is below the minimum allowed value.
numberIsTooLargeThe identified field contains a number that is above the maximum allowed value.
integerIsTooSmallThe identified field contains an integer that is below the minimum allowed value.
integerIsTooLargeThe identified field contains an integer that is above the maximum allowed value.
stringIsTooShortThe identified field contains a string that is below the minimum allowed length.
stringIsTooLongThe identified field contains a string that is above the maximum allowed length.
stringFailedRegexCheckThe identified field contains a string that does not match the regex expression for this field.
panFailedLuhnCheckThe identified field contains a PAN that has failed the Luhn check.
dateHasInvalidFormatThe identified field contains a date that does not match the expected date format.