Error Object


If a request fails, the PB Complete Shipping APIs return an error object in the response body. Pitney Bowes provides a standard error object that can be returned for all errors. To use the standard object, set the X-PB-UnifiedErrorStructure header to true with each API request. Any errors you encounter will use the standard structure described in the table below.

Note: If you omit the X-PB-UnifiedErrorStructure header or set it to false, the APIs will return one of several different legacy formats for errors. The format returned depends on the component where the error occurred. Pitney Bowes recommends setting the X-PB-UnifiedErrorStructure header to true with each API request.

Error Object Fields

The standard error object (available when the X-PB-UnifiedErrorStructure header is set to true) uses the following fields:

Field Type Description
errors Array[Object] Contains the error or errors. If there are multiple objects in the array, each object defines a different error.
    errorCode String The error code.
    errorDescription String The reason for the failure.
    additionalInfo String

Details about the failure.

Note: If an error does not use this field, the field will be either left out or given the null value.

    parameters array[String]

The fields that might be incorrect in the request.

Note: If an error does not use this array, the array will be either left out or empty.

Example Error Objects

Example 1

In the following example, an error is returned for a shipment that did not include a postal code in the fromAddress. The postal code is required:

{
    "errors": [ {
        "errorCode": "1019003",
        "errorDescription": "Either Invalid or missing street or stateProvince or postalcode.",
        "additionalInfo": "postalCode field length field either exceeds allowed limit or is in invalid format",
        "parameters": ["fromAddress postalCode"]
    } ]
}

Example 2

In the following example, multiple errors are returned for a merchant registration that included a merchant email but no merchant address:

{
    "errors": [ {
        "errorCode": "validation.failed",
        "errorDescription": "cityTown: may not be null",
        "additionalInfo": null,
        "parameters": []
    }, {
        "errorCode": "validation.failed",
        "errorDescription": "postalCode: may not be null",
        "additionalInfo": null,
        "parameters": []
    }, {
        "errorCode": "validation.failed",
        "errorDescription": "countryCode: may not be null",
        "additionalInfo": null,
        "parameters": []
    } ]
}