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 |
---|---|
| Required; a descriptive, all caps, underscore-separated string (e.g., |
| Required; a description of the error that is suitable for display to end users |
| Optional; an array containing the path(s) to one or more of the request object’s offending properties using dot notation (e.g., |
| Optional; a string containing a reference to the request’s error |
| Optional; typically a regular expression used to evaluate the property |
| 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"
}
]
}