Error Object


If a request fails, the APIs return the standard error object described here.

To return the standard error object, some API calls require the X-PB-UnifiedErrorStructure request header. The documentation indicates when the header is required for an API call. Without the header, the API call will return errors in a legacy error format.

Error Object Fields

The standard error object 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.

errors.errorCode

String

The error code.

errors.errorDescription

String

The reason for the failure.

errors.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.

errors.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": []
    } ]
}