DHL Fehlerbehebung
Lösungen für häufige Probleme mit dem DHL Connector.
Authentifizierungsfehler
HTTP 401 — Unauthorized
| Ursache | Lösung |
|---|---|
| Zugangsdaten falsch | API User / API Password im DHL Setup prüfen |
| Token abgelaufen | Verbindungstest ausführen → Token wird automatisch erneuert |
| Sandbox-/Produktions-Mismatch | Sicherstellen, dass die API-URL zur Umgebung passt (Sandbox vs. Production) |
Verbindungstest
Der Verbindungstest (Test Connection im DHL Setup) prüft die Authentifizierung und erneuert bei Erfolg automatisch den Token. Führen Sie diesen bei 401-Fehlern immer zuerst aus.
HTTP 403 — Forbidden
| Ursache | Lösung |
|---|---|
| Fehlende API-Berechtigung | Im DHL GKP prüfen, ob die API für Ihren Vertrag freigeschaltet ist |
| IP-Beschränkung aktiv | Falls DHL IP-Filtering aktiviert hat, die BC-Server-IPs freigeben lassen |
| Falsches Produkt | Prüfen, ob das Produkt in Ihrem DHL-Vertrag enthalten ist |
Label-Erstellungsfehler
No contract line found for destination
Das gewählte Zielland ist in keiner Vertragsposition hinterlegt.
Lösung:
- Öffnen Sie Profile → gewünschtes Profil
- Prüfen Sie die Contract Lines (Vertragspositionen)
- Stellen Sie sicher, dass eine Position für die gewünschte Zone existiert:
- Domestic (DE) für innerdeutschen Versand
- EU für EU-Länder
- International für Nicht-EU-Länder
- Prüfen Sie, ob das Produkt in der Vertragsposition korrekt zugeordnet ist
→ Details: Profile & Vertragspositionen
Weight exceeds maximum for product
Das Sendungsgewicht übersteigt das Maximalgewicht des automatisch gewählten Produkts.
Lösung:
- Standard-Paket (V01PAK, V54EPAK, V53WPAK): Max. 31,5 kg
- Kleinpaket (V62KP): Max. 1 kg
- Warenpost International (V66WPI): Max. 1 kg
- Gewicht im Label-Dialog korrigieren oder anderes Produkt manuell wählen
HTTP 400 — Bad Request
Ungültige Sendungsdaten. Häufige Ursachen:
| Feld | Häufiger Fehler | Lösung |
|---|---|---|
| PLZ | Falsches Format (z.B. "D-12345" statt "12345") | PLZ ohne Länderpräfix angeben |
| Land | Name statt ISO-Code | ISO alpha-2 Code verwenden (DE, AT, CH) |
| Gewicht | 0 oder leer | Mindestens 1 g angeben |
| Hausnummer | Fehlt | Straße und Hausnummer getrennt oder zusammen angeben |
| Ungültiges Format | Gültige E-Mail-Adresse eingeben (für VAS-Benachrichtigungen) |
Tagesabschluss-Fehler
No shipments to manifest
Es gibt keine offenen Sendungen zum Manifestieren.
Mögliche Ursachen:
- Tagesabschluss wurde bereits durchgeführt
- Labels wurden storniert
- Labels wurden mit einem anderen Profil erstellt (anderer Account)
Manifest document not available
Das Manifest-Dokument ist noch nicht bereit.
Lösung: Warten Sie 1–2 Minuten und versuchen Sie erneut, das Dokument abzurufen. DHL benötigt kurze Verarbeitungszeit nach dem Abschluss.
Retouren-Fehler
Receiver ID invalid
Die konfigurierte Retoure-Receiver-ID ist ungültig.
Lösung:
- Öffnen Sie das DHL Setup
- Prüfen Sie das Feld Retoure Receiver ID
- Falls leer: Der ISO-3-Code Ihres Landes wird automatisch verwendet
- Falls gefüllt: Genauen Wert mit den DHL-Vertragsdaten abgleichen
Rate Limiting
HTTP 429 — Too Many Requests
| Kontext | Limit | Lösung |
|---|---|---|
| Tracking API | 250 Anfragen/Tag | Tracking-Abrufe reduzieren (nur bei Status-Änderung) |
| Shipping API | Hoch (selten erreicht) | Bei Bulk-Label-Erstellung Pausen einbauen |
Tracking-Limit
Die DHL Track & Trace API erlaubt max. 250 Anfragen pro Tag (Sandbox: 50). Der Connector prüft nur aktive Sendungen und überspringt bereits zugestellte.
Sandbox vs. Produktion
| Aspekt | Sandbox | Produktion |
|---|---|---|
| API-URL | https://api-sandbox.dhl.com |
https://api-eu.dhl.com |
| Credentials | Test-Credentials (im DHL Developer Portal) | Echte GKP-Credentials |
| Labels | Werden als "MUSTER" markiert | Echte, versandfähige Labels |
| Tracking | Simulierte Events | Echte Sendungsverfolgung |
| Manifest | Keine echte Übergabe | Bindende Übergabe an DHL |
Umschalten zwischen Sandbox und Produktion
- Öffnen Sie das DHL Setup
- Ändern Sie die API Base URL
- Aktualisieren Sie die Credentials (Sandbox/Produktion haben unterschiedliche)
- Führen Sie einen Verbindungstest durch
Sandbox-Labels nicht versenden!
Sandbox-Labels sind nicht versandfähig. Sie werden mit "MUSTER" / "SAMPLE" markiert und von DHL nicht verarbeitet.
Label-Format-Probleme
Label wird nicht korrekt gedruckt
| Problem | Ursache | Lösung |
|---|---|---|
| Zu groß/klein | Falsches Label-Format | Format im DHL Setup anpassen (A4 vs. 100×70mm) |
| Unleserlich | ZPL auf PDF-Drucker | Doc Format von ZPL2 auf PDF ändern (oder umgekehrt) |
| Seitenumbruch | Falsche Labelgröße für Drucker | Label Print Format prüfen (muss zum physischen Etikett passen) |
→ Details: DHL Setup
Fehler-Klartext & Vorab-Prüfung
DHL-Fehler im Klartext
Kryptische DHL-API-Fehlermeldungen werden automatisch in konkrete Handlungshinweise übersetzt und direkt im Fehlerdialog angezeigt. Statt eines technischen API-Codes erhalten Sie einen Hinweis, welche Einstellung wo zu korrigieren ist.
| Fehlerbereich | Bedeutung | So beheben Sie es |
|---|---|---|
| Abrechnungsnummer / EKP | Die 14-stellige Abrechnungsnummer ist falsch oder unvollständig (EKP 10 Stellen + Verfahren 2 Stellen + Teilnahme 2 Stellen) | EKP, Verfahren und Teilnahme in der Vertragsposition prüfen; zusammen genau 14 Stellen |
| Service nicht gebucht | Das verwendete Produkt/Verfahren ist im DHL-Vertrag nicht freigeschaltet | Im DHL GKP prüfen, ob das Produkt für Ihren Vertrag gebucht ist |
| Profilname | Der hinterlegte Profilname (Billing/Shipper-Profil) existiert bei DHL nicht | Profilname im Setup gegen die GKP-Konfiguration abgleichen |
| Retoure-Aktivierung | Retoure ist für den Account nicht aktiviert | Retoure-Service im DHL GKP freischalten lassen, anschließend Receiver ID prüfen |
| Adresse / Leitcodierung | Die Empfängeradresse kann von DHL nicht leitcodiert werden (PLZ, Ort, Straße passen nicht zusammen) | Adresse korrigieren — PLZ, Ort und Straße auf Konsistenz prüfen |
| Gewicht | Gewicht fehlt, ist 0 oder überschreitet das Produktmaximum | Gewicht im Label-Dialog korrigieren oder passendes Produkt wählen |
| Paketmaße | Die angegebenen Maße (L/B/H) überschreiten die zulässigen Grenzen des Produkts | Maße korrigieren oder ein größeres Produkt verwenden (Auto-Upsize) |
| Nachnahme / IBAN | Bankverbindung für Nachnahme (NN) fehlt oder die IBAN ist ungültig | Gültige IBAN/BIC im Setup bzw. im Nachnahme-VAS hinterlegen |
Vollständige Antwort im Activity Log
Der übersetzte Hinweis zeigt die wahrscheinlichste Ursache. Die vollständige DHL-API-Antwort mit allen Detail-Codes finden Sie weiterhin im Activity Log.
Aktion "Prüfen" (Validate) — Vorab-Validierung ohne Kosten
Im Dialog Versandlabel erstellen gibt es die Aktion Prüfen (Validate). Sie führt DHLs Vorab-Validierung (validate=true) aus und meldet erkannte Probleme im Klartext zurück — als Diagnosewerkzeug bevor Sie das Label erzeugen.
- Kein Label, keine Kosten: Es wird kein Label erstellt und es entsteht keine Abrechnung.
- Genau die eingegebenen Daten: Validiert exakt die im Dialog eingegebene Adresse, das Gewicht und die Maße.
- Für Aufträge und Lieferungen: Funktioniert sowohl für Verkaufsaufträge als auch für gebuchte Verkaufslieferungen.
So nutzen Sie es: Öffnen Sie den Label-Dialog, kontrollieren/korrigieren Sie Adresse, Gewicht und Maße und klicken Sie Prüfen. Beheben Sie gemeldete Probleme (siehe Tabelle oben) und erstellen Sie das Label erst danach.
Plattformweit verfügbar
Die Aktion Prüfen und die Klartext-Fehlerhinweise stehen für alle merchantCENTRAL Shipment-Connectors zur Verfügung (DHL, DHL Express, DPD, GLS, UPS, Hermes, Rhenus), nicht nur für DHL.
Support-Kontakt
Falls die obigen Lösungen nicht helfen:
- Activity Log prüfen: Im merchantCENTRAL Activity Log finden Sie die vollständige API-Anfrage und -Antwort
- DHL Developer Portal: developer.dhl.com — API-Dokumentation und Sandbox-Zugang
- DHL GKP: Geschäftskundenportal für Vertragsfragen