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

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