Errors

All API calls use the NGP VAN standard error format for returning errors. The response will always have an HTTP status code of 400 or greater and a single property called errors which is an array of one or more standard Error objects. These objects have the following properties:

Property

Description

code

Required; a descriptive, all caps, underscore-separated string (e.g., CHECK_OUTS_TOO_FREQUENT)

text

Required; a description of the error that is suitable for display to end users

properties

Optional; an array containing the path(s) to one or more of the request object’s offending properties using dot notation (e.g., primaryAddress.streetAddress). If the offending property is on an object in an array, the property will use square brackets and a zero based index of the item in the original array.

referenceCode

Optional; a string containing a reference to the request’s error

hint

Optional; typically a regular expression used to evaluate the property

resourceUrl

Optional; a link to technical resources to assist developer with resolving the error

In the following example, an error is reported that is not tied to a specific property.

{
  "errors": [
    {
      "text": "Events are not supported in this database",
      "code": "EVENTS_NOT_SUPPORTED_IN_DB"
    }
  ]
}

In the following example, a single property of a request has failed.

{
  "errors": [
    {
      "properties": [
        "creditCardNumber"
      ],
      "text": "Credit card number must be digits only",
      "code": "INVALID_PARAMETER"
    }
  ]
}

In the following example, two properties of the request contributed to a single failure.

{
  "errors": [
    {
      "properties": [
        "dateBegin",
        "dateEnd"
      ],
      "text": "dateEnd must come after dateBegin",
      "code": "INVALID_PARAMETER"
    }
  ]
}

The following example illustrates how to report a failure in the second phone (zero-based index) in a person object’s array of phones.

{
  "errors": [
    {
      "properties": [
        "phones[1].extension"
      ],
      "text": "Extensions must be numeric",
      "code": "INVALID_PARAMETER"
    }
  ]
}

In the following example, the request’s phone number is invalid. The regular expression used to validate is provided as a hint.

{
  "errors": [
    {
      "properties": [
        "phones[0].number"
      ],
      "text": "A valid phone number is required",
      "hint": "^1?[2-9][0-8]\d[2-9]\d{6,6}$",
      "code": "INVALID_PARAMETER"
    }
  ]
}

The following contains a link to a resource that describes the protocols supported by the service.

{
  "errors": [
    {
      "properties": [
        "sourceFile.fileUrl"
      ],
      "text": "The URL provided does not represent a supported protocol",
      "resourceUrl": "https://api.ngpvan.com/support/supportedProtocols",
      "code": "UNSUPPORTED_PROTOCOL"
    }
  ]
}

The following contains a reference code to allow developers to communicate with NGP VAN staff about the error encountered.

{
  "errors": [
    {
      "properties": [
        "canvassResponses[1].VANID"
      ],
      "text": "You do not have access to the VANID", 
      "code": "INACCESSIBLE_VANID",
      "referenceCode": "ABC-123-DEF-456"
    }
  ]
}