Skip to content

Troubleshooting

Common errors and solutions when using the DHL Express Connector.

Connection Errors

HTTP 401 — Unauthorized

Cause: API credentials (username or password) are invalid or expired.

Solution:

  1. Open the DHL Express Setup
  2. Click the Username field and re-enter the username
  3. Click the Password field and re-enter the password
  4. Run Test Connection

Sandbox vs. Production

Sandbox and production use different credentials. Ensure you are using the correct credentials for the active environment.

HTTP 403 — Forbidden

Cause: Your DHL Express account lacks permissions for the requested operation.

Solution:

  • Verify your API access is enabled for the required endpoints
  • Ensure the API user has permissions for Shipment, Tracking, and Pickup
  • Contact your DHL Express representative

HTTP 408 / Timeout

Cause: The MyDHL API is not responding within the time limit.

Solution:

  • Retry the operation (temporary network issue)
  • Check your internet connection
  • Check the DHL Express API status

Label Creation

HTTP 400 — "Missing phone number"

Cause: DHL Express requires a phone number for both shipper and recipient.

Solution:

  • Verify the Shipper Phone field is filled in the setup
  • Verify the recipient phone number is provided in the shipment

HTTP 400 — "Invalid account number"

Cause: The account number is invalid or incorrectly formatted.

Solution:

  • DHL Express account numbers are 9 digits
  • Check Shipper Account No. and Billing Account No. in setup
  • Ensure no spaces or special characters

HTTP 400 — "Invalid postal code"

Cause: The postal code format does not match the destination country.

Solution:

Country Format Example
Germany (DE) 5 digits 90402
United Kingdom (GB) Alphanumeric SW1A 1AA
USA (US) 5 or 9 digits 10001 / 10001-7890
France (FR) 5 digits 75001
Netherlands (NL) 4 digits + 2 letters 1012 AB

HTTP 422 — "Product not available"

Cause: The selected product is not available for this route.

Solution:

  • Use the Rate Query to find available products
  • Express 9:00 (K) and Express 12:00 (T) are not available on all routes
  • Economy Select (H) is only available for certain countries

HTTP 400 — "Weight exceeds maximum"

Cause: Weight exceeds the maximum for the package type or route.

Solution:

  • DHL Express standard maximum: 70 kg per package
  • Ensure weight is specified in kilograms (not grams)
  • For heavy shipments: contact DHL Express Freight

Pickup Errors

"Pickup already exists"

Cause: A pickup has already been booked for this day and location.

Solution:

  • With Auto Pickup: DHL recognizes the existing booking — no action needed
  • Manual: Check the pickup list for existing bookings

"Ready time in the past"

Cause: The specified ready time is in the past.

Solution:

  • Adjust the Pickup Ready Time in setup
  • For same-day pickup: ready time must be at least 30 minutes in the future
  • For next-day pickup: change the pickup date

Customs / International

"Customs declaration required"

Cause: Customs declaration is required for shipments to non-EU countries.

Solution:

  1. Enable Paperless Trade in setup (recommended)
  2. Or fill in the customs fields: Export Description, HS Code, Customs Value, Country of Origin

"EORI number required"

Cause: EORI number is required for commercial shipments to certain countries.

Solution:

  • Enter your EORI number in Setup → Customs → Shipper EORI

License Errors

"Module not licensed"

Cause: The DHL Express Connector has no valid license.

Solution:

  1. Open the DHL Express Setup
  2. Check the License Status
  3. If "Unregistered": Click Register Demo for a 30-day trial
  4. If "Expired": Contact support for license renewal

Tracking stops updating

Polling stops silently when the module can no longer be used — deliberately, instead of failing hourly with an error that only fills the job queue log. Check in this order:

Check Where Expected
Module licence merchantCENTRAL Setup → Modules Status Active or a running Demo
Provider activated Shipment provider list Enabled is set
Tracking switched on The connector's setup card Tracking Enabled
Schedule Job queue entry Status Ready, not On Hold

Without a valid licence or a running demo the connector no longer asks the carrier. The schedule itself stays and picks its work up again as soon as the licence is valid.

Support

If you cannot resolve an issue:

  1. Note the complete error message (including HTTP status code)
  2. Check the Activity Log in the merchantCENTRAL Dashboard
  3. Contact support at support@merchantcentral.de