Errors

Our errors have a single top-level error, this is provided in your error response to summarize the error. The response contains an errorName that is both human-readable and machine-readable, with a human-readable message to add context to help you diagnose the error.

If there are multiple errors, the response includes all the errors in anested listwithin the top-level error.

Our APIs are aligned on standard errors, this ensures consistency when diagnosing potential errors.

Generic Error Format

Copied!
{
  "errorName": "errorName",
  "message": "human readable message"
}
FieldTypeOptionalDescription
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 FieldTypeOptionalDescription
jsonPathStringThis field represents theJSONPathof the element within the request body associated with the error.

Examples

An example error response:

Copied!
{
  "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:

Copied!
{
  "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

Top Level Errors

Error NameHTTP codeDescriptionAdditional fields
internalErrorOccurred500An error occurred within the service (potentially due to an interaction with a downstream service).
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 a valid JSON. This body is required to be a valid JSON.
bodyDoesNotMatchSchema400There were field validation errors. The errors that occurred are within the validationErrors array.validationErrors: Array of field validation 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.