Most errors that occur with the DHL shipping integration can already be resolved using the information provided in the error message. In this article, in addition to these messages, you will also find some other error messages related to the DHL Versand extension along with their solutions. In all cases: If the problem persists after following the described steps, feel free to contact our Support.

If the following error message appears, it means the user in the business customer portal has not been assigned the correct profile.

Error
​The shipment could not be created due to errors: The DHL BCP API responded with an error: Unknown group profile.

To fix this problem, log in to the DHL business customer portal. Under Paket & Waren → Versenden → Einstellungen → Nutzergruppen, you can assign the STANDARD_GRUPPENPROFIL to the user.

The following error message points to a problem with the printer settings.

Error
​The shipment could not be created due to errors: The DHL BCP API responded with an error: invalid printer settings - please adjust your printer settings in the DHL business customer portal "Sending > Basic Settings > General" and save them in any case with occupied user

To fix this problem, navigate in the DHL business customer portal to Paket & Waren → Versenden → Einstellungen → Allgemeine Einstellungen and disable the local printer settings there.

If the following error message appears when creating shipping or return labels, it may be because two-factor authentication (2FA) is enabled for the DHL user being used.

Error
​The shipment could not be created due to errors: The DHL Parcel API responded with an error: DHL Authorisation Server: Access denied, direct grant with security profile enhanced not allowed.

The DHL API does not support authentication with two-factor authentication (2FA) enabled. If 2FA is active in the DHL business customer portal, Pickware cannot establish a connection to the API.

The following error message indicates that the terms of use in the DHL customer account have changed and need to be accepted again.

Error message: There occurred an unexpected error: Client error: `GET https://geschaeftskunden.dhl.de/customeradministration/api/v1/user` resulted in a `403 Forbidden` response

To resolve this, log in to the DHL business customer portal, click on your username in the top right corner, and then click Benutzer verwalten. A pop-up window will open where you can accept the new terms of use.

The following error message indicates that the sender address is incomplete.

The sender address is missing the following property: Name, company or address addition.

In this case, go to Settings → Extensions → Versandetiketten allgemein in your Shopware Admin and enter the missing data there. You can find more information on the available settings here.

The following error message points to problems with the stored billing number.

Hard validation error occured. Die ausgewählte Abrechnungsnummer steht nicht zur Verfügung

In this case, the number stored under Settings → Extensions → Versandetiketten DHL → Vertragsinformationen does not match the number in the DHL business customer portal. You can find the correct numbers in the DHL business customer portal in the user menu at the top right under Vertragsdaten. The relevant part is the last two digits of the billing numbers.

If an error message occurs when creating shipping or return labels, it may be because the contract data cannot be retrieved correctly from the DHL business customer portal. First check in your Shopware Admin under Extensions → Settings → Versandetiketten DHL using the Vertragsdaten abrufen button whether retrieving the contract data works at all.

If your contract data can be retrieved correctly but you still cannot create shipping labels, please contact Support.

If retrieving the contract data fails, proceed as follows:

If this error message occurs when creating shipping or return labels, there are two possible causes:

Note that the Benutzername must be entered exactly as it appears (including upper/lower case) in the DHL business customer portal under Benutzer verwalten.

To check how your username is stored at DHL, proceed as follows:

The settings for DHL shipping can also be configured at the Sales Channel level if needed. If the error message still appears despite entering the correct credentials, also check the settings for the individual Sales Channels.

Generally, the settings made under Alle Verkaufskanäle are inherited by the other Sales Channels. You can recognize this by the icon in front of the field name once you have selected a Sales Channel. However, it is also possible to exclude individual fields from this by clicking on the icon. Below you can see an example of a non-inherited field (Benutzername) and an inherited field (Passwort).

To use the products DHL Retoure Online and DHL Retoure International, you need:

A contract for DHL Retoure Selbstzahler is not sufficient in this case! Please contact your DHL representative to adjust your contract.

This error message appears if you have selected the DHL product DHL Paket for a shipment outside of Germany. Select DHL Paket International instead and create the label again.

This error message appears if you have selected the testing web service in the DHL configuration but have not entered the correct credentials. In this case, you need to enter the API key and API secret of your DHL developer portal account instead of your regular credentials.

This error message appears if one of the fields name1, name2, or name3 is longer than 50 characters. The name fields are automatically populated as follows:

If a company is specified:

If no company is specified:

Check whether, for example, the combination of company and department or first name and last name could be too long, and adjust the entries accordingly. You can find a tool for counting characters, for example, here.

This error message appears if the email address stored in the order is longer than the limit permitted by DHL for this field. In this case, DHL rejects the creation of the shipping label with the following error message.
The DHL Express API could not process the request:

This occurs particularly often with orders from marketplaces such as Amazon, since the buyer email addresses transmitted there (e.g. …@marketplace.amazon.com.de) can be very long. In this case, shorten the email address in the affected order and create the shipping label again afterwards. If the full email address is absolutely required, the label can alternatively be created directly in the DHL Express portal.

Pickware only supports DHL Retoure Online. The DHL Retoure Selbstzahler variant is not compatible and therefore cannot be used for the automatic creation of return labels. If DHL Retoure Selbstzahler has nevertheless been set for a shipping method or product, this results in this error message when creating a shipping label. In this case, make sure that the correct return type DHL Retoure Online is used.

If the weight of your packages is not rounded correctly, this may be due to an incorrect setting in your PHP configuration. Check in your php.ini whether the value -1 is set for serialize_precision, and if not, adjust the value accordingly. You can find more information, for example, here.

If your shipping labels are created as a Premium Label despite the premium function being disabled, this is because most EU countries do not offer economy products, and in this case, DHL automatically activates the premium function.

This error message can appear if the option Label nur erzeugen, wenn Adresse leitcodierbar is enabled when creating a shipping label.

When leitcodierbar validation is enabled, DHL checks whether the combination of street and postal code is uniquely stored in the system. However, some large customers, such as universities or government agencies, use different postal codes for postal and street addresses. As a result, the address may not be correctly matched by the DHL system.

A university in Berlin uses 10099 Berlin as its general postal address, but also uses 10117 Berlin for street addresses. In this case, label creation can only be completed successfully with the correct street postal code (10117 Berlin). If 10099 is used, the error message appears.

Use the correct street postal code, or simply disable the option Label nur erzeugen, wenn Adresse leitcodierbar to create the shipping label anyway.