The error code returned in the body of the error response is structured as follows:

Example:

400.0204002

400 - HTTP standard Error code. Also returned in the response header.

02 - refers to a specific service.

Following are the service specific codes.

• 00 - Gateway-related errors AND errors returned by more than one API
• 02 - Label
• 03 - Tracking
• 04 - Manifest
• 06 - Product Finder
• 09 - DTC
• 10 - Transportation
• 13 - Return Label

04 - indicates API version number. Currently, only

04 is in use. For generic errors, version number is

00 as this does not change between versions.

002 - refers to a serialized error number to make each error code unique. Refer below for the complete list of error codes.

Sample error response is shown here:

{
   "type":"https://api.dhlecs.com/docs/errors/400.0000001",
   "title": "Mandatory Query Parameter Missing",
   "invalidParams": [
       {
           "name": "format",
           "reason": "Label format is a required query parameter"
       }
   ]
}

invalidParams is an array that provides details on specific error fields and none, one or more errors can be returned. For generic errors, the

invalidParams object will be omitted from the response. We recommend using the error type, error code and title to get help regarding the error.

Also, some error messages will not have the

name element if the error is generic to the request rather than a specific element. However, the invalidParams object will be returned with just the reason in order to provide more detail on the error beyond what's described in the error title.

DHL eCommerce uses HTTP status codes for errors (e.g. 400, 401, 403). These error codes are explained in detail in the

List of Error Codes section. Within each status code there are more specific error codes available in the body. All error responses use the following format:

M- Mandatory O- Optional C- Conditional N- Not Applicable

Information about each error code can be directly referenced by appending the error code to the URL. For example -

https://api.dhlecs.com/docs/errors/400.0204003

The same error URLs are also returned in the API responses when there is an error. This allows clients to quickly get detailed information on each type of error.

A 400 error code is returned when the server cannot or will not process the request due to a client error.

400.0000001

Title: Mandatory query parameter(s) missing or invalid query parameter(s) present

Used in: POST Label, GET Label, GET Tracking

Description:

The server cannot or will not process the request due to a client error. In this case, one or more mandatory query parameter name(s) were missing from the request or invalid query parameter name(s) were present.

400.0000002

Title: Query parameter value could not be found or is invalid.

Used in: GET Label API

Description:

The server cannot or will not process the request due to a client error. In this case, a query parameter value requested was not found in the database.

400.0000003

Title: Invalid request

Used in: All APIs

Description:

The server cannot or will not process the request due to a client error. In this case, a malicious request was detected hence the request was denied.

400.0000004

Title: Invalid grant type

Used in: Access Token API

Description:

Invalid Grant type error occurs when the grant type header is not sent in the Auth request or an invalid value has been provided. We use OAuthV2 Basic Authentication that expects a grant_type of client_credentials to authenticate the credentials and provide an access token.

400.0000999

Title: Unknown exception - bad request

Used in: Label, Manifest, Tracking, Transportation, Product Finder, DTC API

Description:

The server cannot or will not process the request due to a client error. Unknown exception due to a bad request occurs when a request could not be processed due to an unexpected error encountered in the API service due to bad data. Unfortunately, additional information cannot be provided about the error in the response itself. Kindly contact support with a snapshot of the error request along with the Correlation ID (if you received one in the response header) and we will be able to assist you.

400.0204002

Title: The supported label formats are ZPL and PNG

Used in: Label API

Description:

This error occurs when an unsupported label format value is requested. The supported label formats are ZPL and PNG.

• ZPL labelData is provided with an encodeType of PLAIN.
• PNG labelData is provided with an encodeType of BASE64.

400.0204003

Title: Static Validation Failed

Used in: Label API

Description:

The server cannot or will not process the request due to a client error. A static validation error occurs when the request could not be validated successfully against the underlying schema. This can be due to missing mandatory fields, incorrect field types used, invalid JSON request body, invalid enum field values sent and more.

More information about which field(s) failed validation are provided in the invalidParams object in the error response. Refer to the latest service schema for the specifications.

400.0204004

Title: Dynamic Validation Failed

Used in: Label API

Description:

The server cannot or will not process the request due to a client error. A dynamic validation error occurs when the request could not be validated successfully against requirements that are specific to the attributes of the request, such as the Ordered Product ID, Country, Postal Code, Weight, Customs Details and many more. This can be due to missing field values, values above or below a certain threshold, values not in specified format and other reasons.

More information about which field(s) failed validation are provided in the invalidParams object in the error response. There are thousands of dynamic validation rules for different combinations of the above parameters.

400.0204005

Title: Data validation failed

Used in: Label API

Description:

The server cannot or will not process the request due to a client error. A Data Validation error occurs due due to bad data in the request, from fields that are critical to identifying the Package and Client Master data such as Pickup number, Distribution Center etc.

400.0204006

Title: Duplicate Validation Failed

Used in: Label API

Description:

The server cannot or will not process the request due to a client error. Duplicate Validation fails when the same Package ID is used in more than one successful Label request. Package ID is the unique identifier from the client for a package. If a label request was submitted earlier but the label was not retreived successfully for any reason, use the GET Label request instead to retrieve an existing label using the same Package ID.

400.0204008

Title: Product finding failed

Used in: Label API

Description:

The server cannot or will not process the request due to a client error. Product finding fails when a suitable product could not be found for the requesed package parameters. This occurs most often due to package being out of weight limit supported by the Product, invalid consignee destination country and a few other reasons.

More information about which field(s) failed validation are provided in the invalidParams object in the error response.

400.0204009

Title: Downstream validation failed

Used in: Label API

Description:

The server cannot or will not process the request due to a client error. Downstream validation fails when there's a known downstream system error from Domestic or International Mail Processing systems beyond what has been validated by the API service. We have minimized this as much as possible by using our own static and dynamic validations.

More information about which field(s) failed validation are provided in the invalidParams object in the error response. Refer to the latest service schema for the specifications.

400.0404001

Title: Static validation failed

Used in: Manifest API

Description:

The server cannot or will not process the request due to a client error. A static validation error occurs when the request could not be validated successfully against the underlying schema. This can be due to missing mandatory fields, incorrect field types used, invalid JSON request body, invalid enum field values sent and more.

More information about which field(s) failed validation are provided in the invalidParams object in the error response. Refer to the latest service schema for the specifications.

400.0404002

Title: Dynamic validation failed

Used in: Manifest API

Description:

The server cannot or will not process the request due to a client error. A dynamic validation error occurs when the request could not be validated successfully against requirements that are specific to the attributes of the request, such as an invalid pickup.

More information about which field(s) failed validation are provided in the invalidParams object in the error response.

400.0604001

Title: Static validation failed

Used in: Product Finder

Description:

The server cannot or will not process the request due to a client error. A static validation error occurs when the request could not be validated successfully against the underlying schema. This can be due to missing mandatory fields, incorrect field types used, invalid JSON request body, invalid enum field values sent and more.

More information about which field(s) failed validation are provided in the invalidParams object in the error response. Refer to the latest service schema for the specifications.

400.0604002

Title: Dynamic Validation Failed

Used in: Product Finder

Description:

The server cannot or will not process the request due to a client error. A dynamic validation error occurs when the request could not be validated successfully against requirements that are specific to the attributes of the request, such as the Ordered Product ID, Country, Postal Code, Weight, Customs Details and many more. This can be due to missing field values, values above or below a certain threshold, values not in specified format and other reasons.

More information about which field(s) failed validation are provided in the invalidParams object in the error response. There are thousands of dynamic validation rules for different combinations of the above parameters.

400.0604003

Title: Data Validation Failed

Used in: Product Finder

Description:

The server cannot or will not process the request due to a client error. A Data Validation error occurs due due to bad data in the request, from fields that are critical to identifying the Package and Client Master data such as Pickup number.

400.0604004

Title: Product Finding Failed

Used in: Product Finder

Description:

The server cannot or will not process the request due to a client error. A Product Finding error occurs when the service cannot find any suitable product for the given combination of parameters in the request. This could be most likely due to the following parameters: weight/value, weight/unitOfMeasure, consigneeAddress/country, distributionCenter and/or an orderedProductId provided that is not valid for the weight provided etc.

400.0904001

Title: Static Validation Failed

Used in: DTC

Description:

The server cannot or will not process the request due to a client error. A static validation error occurs when the request could not be validated successfully against the underlying schema. This can be due to missing mandatory fields, incorrect field types used, invalid JSON request body, invalid enum field values sent and more.

More information about which field(s) failed validation are provided in the invalidParams object in the error response. Refer to the latest service schema for the specifications.

400.0904002

Title: Processing Error

Used in: DTC

Description:

The server cannot or will not process the request due to a client or server error. this error occurs due to bad data in the request, from fields that are critical to identifying the Package/customer, item-seller, pickup number, country, item-id , issue with sheets , missing property that needed for calculation , master data etc.

400.0904003

Title: Data Validation Failed

Used in: DTC

Description:

The server cannot or will not process the request due to a client error. This error occurs due to bad data in the request, from fields that are critical to identifying the Package/customer, item-seller, pickup number, country, item-id , issue with sheets , missing property that needed for calculation , master data etc.

Request can be bad due to one of the following reasons -

• Invalid combination of pickup account no and item seller
• currency does not exist in master data
• sender address country or consignee address country does not exist in sheets present in master data
• sender address country and consignee address country should not be same.
• Item id should not be duplicate under custom details

The above list is for example only and should not be considered a complete reference.

400.1004001

Title: Static Validation Failed

Used in: Transportation API

Description:

The server cannot or will not process the request due to a client error. A dynamic validation error occurs when the request could not be validated successfully against requirements that are specific to the attributes of the request, such as the pickup account , postal code, bolNumbers and many more. This can be due to missing field values, values above or below a certain threshold, values not in specified format and other reasons.

More information about which field(s) failed validation are provided in the invalidParams object in the error response.

400.1004002

Title: Data Validation Failed

Used in: Transportation API

Description:

The server cannot or will not process the request due to a client error. A dynamic validation error occurs when the request could not be validated successfully against requirements that are specific to the attributes of the request, such as the pickup account , postal code, bolNumbers and many more. This can be due to missing field values, values above or below a certain threshold, values not in specified format and other reasons.

More information about which field(s) failed validation are provided in the invalidParams object in the error response.

400.1304001

Title: The supported label formats are ZPL, PNG and PDF

Used in: Return Label API

Description:

The label format requested in not valid. Send one of the supported label formats in the request query parameters.

400.1304002

Title: Static Validation Failed

Used in: Return Label API

Description:

The server cannot or will not process the request due to a client error. A static validation error occurs when the request could not be validated successfully against the underlying schema. This can be due to missing mandatory fields, incorrect field types used, invalid JSON request body, invalid enum field values sent and more.

More information about which field(s) failed validation are provided in the invalidParams object in the error response. Refer to the latest service schema for the specifications.

400.1304003

Title: Dynamic Validation Failed

Used in: Return Label API

Description:

The server cannot or will not process the request due to a client error. A dynamic validation error occurs when the request could not be validated successfully against requirements that are specific to the attributes of the request, such as the Ordered Product ID, Country, Postal Code, Weight, Customs Details and many more. This can be due to missing field values, values above or below a certain threshold, values not in specified format and other reasons.

More information about which field(s) failed validation are provided in the invalidParams object in the error response. There are thousands of dynamic validation rules for different combinations of the above parameters.

400.1304004

Title: Data Validation Failed

Used in: Return Label API

Description:

The server cannot or will not process the request due to a client error. A Data Validation error occurs due due to bad data in the request, from fields that are critical to identifying the Package and Client Master data such as Pickup number, Distribution Center etc.

400.1304005

Title: Product Finding Failed

Used in: Return Label API

Description:

The server cannot or will not process the request due to a client error. A Product Finding error occurs when the service cannot find any suitable product for the given combination of parameters in the request. This could be most likely due to the following parameters: weight/value, weight/unitOfMeasure, consigneeAddress/country, distributionCenter and/or an orderedProductId provided that is not valid for the weight provided etc.

400.1304006

Title: Return Address Validation Failed

Used in: Return Label API

Description:

The Return Address provided is not valid hence a label cannot be generated for this request.

Similar to 403 Forbidden, but specifically for use when authentication is required and has failed or has not yet been provided.

401.0000001

Title: Internal gateway authentication error

Used in: Label, Manifest, Tracking, Transportation, Product Finder, DTC API

Description:

Internal Gateway Authentication error occurs when authentication fails between the API gateway and the internal API services. This is not a client-related error and is not due to the client credentials or access token provided. Please report this error with the error code mentioned above for it to be addressed immediately.

401.0000002

Title: Access token invalid

Used in: Label, Manifest, Tracking, Transportation, Product Finder, DTC API

Description:

Invalid Token error occurs when authentication is required and has failed or has not yet been provided. This error specifically means that the access token has not been provided in the request or the token is invalid.

Kindly refer to the documentation on how to obtain a token using the Access Token API.

401.0000005

Title: Invalid client

Used in: Access Token, Label, Manifest, Tracking, Transportation, Product Finder, DTC API

Description:

Invalid Client error occurs when authentication is required and has failed or has not yet been provided. This can also mean that the user does not have valid authentication credentials for the target resource.

Client can be invalid due to one of the following reasons -

• Invalid status of developer. The developer (client) status may be unapproved, revoked or inactive
• Invalid status of app. The application status under the developer could be unapproved, revoked or inactive
• Invalid API Key for given resource. You have supplied a valid key however the key does not have access to the requested resource.
• The application (client) may be unapproved for the API product that's being requested
• The Client ID for the application may have been revoked or not yet approved.

401.0000006

Title: Access token expired

Used in: Label, Manifest, Tracking, Transportation, Product Finder, DTC API

Description:

Expired Token error occurs when authentication is required and has failed or has not yet been provided. This error specifically means that the access token provided has expired. The token generated expires in certain amount of time hence a new token must be generated periodically.

Kindly refer to the documentation on how to obtain a new token using the Access Token API.

401.0000007

Title: Invalid credentials

Used in: Access Token API

Description:

Invalid Credential error occurs when authentication is required but

• credentials are incorrect hence authentication has failed
• credentials have not been provided
• an unsupported Authorization credential has been provided

We require Basic Authentication with Client ID (Username) and Client Secret (Password) which must be joined with a colon (:), converted to a Base 64 string and sent as Authorization header in the Access Token API to obtain an access token. The Access token is required when calling all other API resources such as Label, Manifest, Tracking.

401.0000008

Title: No credentials provided

Used in: Access Token API

Description:

No credentials provided error occurs when authentication credentials has not been provided. We require OAuthV2 Basic Authentication with Client ID (Username) and Client Secret (Password) which must be provided in the Access Token API to obtain an access token. The Access token is required when calling all other API resources such as Label, Manifest, Tracking.

The requested resource could not be found but may be available in the future. Subsequent requests by the client are permissible.

Just so you know, in a worst case scenario, you might see a generic version of this error that our service is completely down that we are not even able to return a proper error message.

{"fault":{"faultstring":"Unable to identify proxy for host: ecs and url: /auth/v4/accesstoken","detail":{"errorcode":"messaging.adaptors.http.flow.ApplicationNotFound"}}}

404.0000001

Title: Undefined resource

Used in: Access token, Label, Manifest, Tracking, Transportation, Product Finder, DTC APIs

Description:

Undefined Resource error occurs when the API gateway does not understand the resource that's being requested.

For example, under shipping/v4, the valid resources are /label and /manifest. If the gateway receives a request for any other resources beyond what is recognized, an undefined resource error is returned. This is also true when the request contains URI parameters before and/or after the accepted resource names.

For example, /shipping/v4/label/print or something equivalent will also return this error.

404.0404003

Title: Manifest not found

Used in: Get Manifest API

Description:

This error will be returned when the manifest requestId is invalid for the specified pickup.

404.1004001

Title: Data Validation Failed

Used in: PICKUP API

Description:

Pickup Shipment does not exist for the given shipment identifier.

Not Acceptable

406.0000001

Title: Accept header requested is not supported

Used in: Access token, Label, Manifest, Tracking, Transportation, Product Finder, DTC APIs

Description:

The HyperText Transfer Protocol (HTTP) 406 Not Acceptable client error response code indicates that the server cannot produce a response matching the list of acceptable values defined in the request's proactive content negotiation headers, and that the server is unwilling to supply a default representation.

The Accept headers that are valid is "application/json"

Accept header is not mandatory for all requests.

A generic error message, given when an unexpected condition was encountered and no more specific message is suitable.

500.1304001-500.1304025

Title: Internal Server Error

Used in: Return Label API

Description:

A generic error message, given when an unexpected condition was encountered and no more specific message is suitable or relevant for the client. This can be due to a number of internal errors that are masked from the client hence there's a range of error codes possible from 001 to 025.

500.0000001

Title: Internal gateway authorization error

Used in: Label, Manifest, Tracking, Transportation, Product Finder, DTC API

Description:

A generic error message, given when an unexpected condition was encountered and no more specific message is suitable. Internal Gateway Authorization error occurs when there is authorization failure between the API gateway and the backend services. This is not a client-side error and is not due to invalid credentials, token or pickup number provided.

500.0000002

Title: Internal gateway server error

Used in: Access token, Label, Manifest, Tracking, Transportation, Product Finder, DTC API

Description:

A generic error message, given when an unexpected condition was encountered and no more specific message is suitable. Internal Gateway Server error occurs when an unknown error has occurred in the API gateway or in the backend service or both.

This may/may not be a client-side error and will require further investigation before the cause of the error can be ascertained. Kindly contact support and provide a snapshot of the request along with the Correlation ID (if available) to get assistance.

500.0000999

Title: Unknown exception - API service

Used in: Label, Manifest, Tracking, Transportation, Product Finder, DTC API

Description:

A generic error message, given when an unexpected condition was encountered and no more specific message is suitable. Unknown Exception in the API service when when we run into a unhandled generic exception in the API service.

While this is completely rare, this may/may not be a client-side error and will require further investigation before the cause of the error can be ascertained. Kindly contact support and provide a snapshot of the request along with the Correlation ID (if available) to get assistance.

500.0204001

Title: Unknown downstream error

Used in: Label API

Description:

Unknown downstream error occurs when there's an unexpected, unknown exception between the internal DHL systems, such as between the API services and the Domestic/International package processing systems.

This may/may not be a client-side error and will require further investigation before the cause of the error can be ascertained. Kindly contact support and provide a snapshot of the request along with the Correlation ID (if available) to get assistance.

500.0604001-500.0604025

Title: Internal Server Error

Used in: Product Finder API

Description:

A generic error message, given when an unexpected condition was encountered and no more specific message is suitable or relevant for the client. This can be due to a number of internal errors that are masked from the client hence there's a range of error codes possible from 001 to 025.

The server cannot handle the request (because it is overloaded or down for maintenance). Generally, this is a temporary state.

The server was acting as a gateway or proxy and did not receive a timely response from the downstream server.