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