DHL Troubleshooting
Solutions for common issues with the DHL Connector.
Authentication Errors
HTTP 401 β Unauthorized
| Cause | Solution |
|---|---|
| Incorrect credentials | Check API User / API Password in DHL Setup |
| Token expired | Run Test Connection β token is automatically renewed |
| Sandbox/production mismatch | Ensure the API URL matches the environment (Sandbox vs. Production) |
Test Connection
The connection test (Test Connection in DHL Setup) verifies authentication and automatically renews the token on success. Always run this first when encountering 401 errors.
HTTP 403 β Forbidden
| Cause | Solution |
|---|---|
| Missing API permission | Check in DHL GKP whether the API is enabled for your contract |
| IP restriction active | If DHL has IP filtering enabled, have the BC server IPs whitelisted |
| Wrong product | Verify the product is included in your DHL contract |
Label Creation Errors
No contract line found for destination
The selected destination country is not configured in any contract line.
Solution:
- Open Profiles β desired profile
- Check the Contract Lines
- Ensure a line exists for the required zone:
- Domestic (DE) for German domestic shipping
- EU for EU countries
- International for non-EU countries
- Verify the product is correctly assigned in the contract line
β Details: Profiles & Contract Lines
Weight exceeds maximum for product
The shipment weight exceeds the maximum weight of the automatically selected product.
Solution:
- Standard parcel (V01PAK, V54EPAK, V53WPAK): Max. 31.5 kg
- Kleinpaket (V62KP): Max. 1 kg
- Warenpost International (V66WPI): Max. 1 kg
- Correct the weight in the label dialog or manually select a different product
HTTP 400 β Bad Request
Invalid shipment data. Common causes:
| Field | Common Error | Solution |
|---|---|---|
| Postal code | Wrong format (e.g., "D-12345" instead of "12345") | Enter postal code without country prefix |
| Country | Name instead of ISO code | Use ISO alpha-2 code (DE, AT, CH) |
| Weight | 0 or empty | Specify at least 1 g |
| House number | Missing | Provide street and house number (together or separately) |
| Invalid format | Enter a valid email address (for VAS notifications) |
End of Day Errors
No shipments to manifest
There are no open shipments to manifest.
Possible causes:
- End of day was already performed
- Labels were cancelled
- Labels were created with a different profile (different account)
Manifest document not available
The manifest document is not yet ready.
Solution: Wait 1β2 minutes and try retrieving the document again. DHL needs brief processing time after closing.
Return Errors
Receiver ID invalid
The configured return Receiver ID is invalid.
Solution:
- Open the DHL Setup
- Check the Retoure Receiver ID field
- If empty: Your country's ISO-3 code is automatically used
- If filled: Verify the exact value against your DHL contract data
Rate Limiting
HTTP 429 β Too Many Requests
| Context | Limit | Solution |
|---|---|---|
| Tracking API | 250 requests/day | Reduce tracking checks (only on status change) |
| Shipping API | High (rarely reached) | Add pauses during bulk label creation |
Tracking Limit
The DHL Track & Trace API allows max. 250 requests per day (Sandbox: 50). The connector only checks active shipments and skips already-delivered ones.
Sandbox vs. Production
| Aspect | Sandbox | Production |
|---|---|---|
| API URL | https://api-sandbox.dhl.com |
https://api-eu.dhl.com |
| Credentials | Test credentials (from DHL Developer Portal) | Real GKP credentials |
| Labels | Marked as "MUSTER" (sample) | Real, shippable labels |
| Tracking | Simulated events | Real shipment tracking |
| Manifest | No actual handover | Binding handover to DHL |
Switching Between Sandbox and Production
- Open the DHL Setup
- Change the API Base URL
- Update the Credentials (sandbox/production use different ones)
- Run a Test Connection
Do not ship sandbox labels!
Sandbox labels are not shippable. They are marked with "MUSTER" / "SAMPLE" and will not be processed by DHL.
Label Format Issues
Label does not print correctly
| Problem | Cause | Solution |
|---|---|---|
| Too large/small | Wrong label format | Adjust format in DHL Setup (A4 vs. 100Γ70mm) |
| Unreadable | ZPL on PDF printer | Change Doc Format from ZPL2 to PDF (or vice versa) |
| Page break | Wrong label size for printer | Check Label Print Format (must match physical label) |
β Details: DHL Setup
Plain-Text Errors & Pre-Check
DHL errors in plain text
Cryptic DHL API error messages are automatically translated into concrete, actionable hints and shown directly in the error dialog. Instead of a technical API code, you get guidance on which setting to correct and where.
| Error area | Meaning | How to fix it |
|---|---|---|
| Billing number / EKP | The 14-digit billing number is wrong or incomplete (EKP 10 digits + procedure 2 digits + participation 2 digits) | Check EKP, procedure and participation in the contract line; together exactly 14 digits |
| Service not booked | The product/procedure used is not enabled in your DHL contract | Check in DHL GKP whether the product is booked for your contract |
| Profile name | The configured profile name (billing/shipper profile) does not exist at DHL | Reconcile the profile name in Setup against the GKP configuration |
| Return activation | Returns are not activated for the account | Have the return service enabled in DHL GKP, then check the Receiver ID |
| Address / routing code | DHL cannot route-code the recipient address (postal code, city, street do not match) | Correct the address β verify postal code, city and street for consistency |
| Weight | Weight is missing, 0, or exceeds the product maximum | Correct the weight in the label dialog or choose a suitable product |
| Package dimensions | The given dimensions (L/W/H) exceed the product's allowed limits | Correct the dimensions or use a larger product (auto-upsize) |
| Cash on delivery / IBAN | Bank details for cash on delivery (COD) are missing or the IBAN is invalid | Enter a valid IBAN/BIC in Setup or in the COD VAS |
Full response in the Activity Log
The translated hint shows the most likely cause. The complete DHL API response with all detail codes is still available in the Activity Log.
"Validate" action β pre-check without cost
The Create Shipping Label dialog provides a Validate action. It runs DHL's pre-validation (validate=true) and reports detected issues in plain text β a diagnostic tool to use before you create the label.
- No label, no cost: No label is created and no charge is incurred.
- Exactly the entered data: Validates precisely the address, weight and dimensions entered in the dialog.
- For orders and shipments: Works for both sales orders and posted sales shipments.
How to use it: Open the label dialog, check/correct the address, weight and dimensions, and click Validate. Resolve any reported issues (see table above), then create the label.
Available platform-wide
The Validate action and the plain-text error hints are available for all merchantCENTRAL shipment connectors (DHL, DHL Express, DPD, GLS, UPS, Hermes, Rhenus), not just DHL.
Support Contact
If the above solutions don't help:
- Check Activity Log: The merchantCENTRAL Activity Log contains the full API request and response
- DHL Developer Portal: developer.dhl.com β API documentation and sandbox access
- DHL GKP: Business customer portal for contract questions