Skip to main content

Common Issues

Quick answers to the most frequent integration problems.

Authentication​

401 Unauthorized on every request​

Cause: Token is missing, expired, or malformed.

Fix:

  1. Confirm you're sending the header: Authorization: Bearer <token> (with the word Bearer)
  2. Check whether your token has expired — use /api/v1/login-extended to see the expireAt field
  3. Re-authenticate with /api/v1/login to get a fresh token

Token expires too quickly​

Cause: Token TTL is configured server-side.

Fix: Contact your DPD account manager to adjust the token TTL for your account. In the meantime, implement token refresh logic that re-authenticates before expiry.

Shipments​

400 Bad Request — validation error​

Cause: A required field is missing or fails validation.

Fix: Check the fieldErrors object in the response — it tells you exactly which field failed and why:

{
  "fieldErrors": {
    "receiver.email": ["REQUIRED_FOR_INTERNATIONAL"],
    "receiver.countryCode": ["NOT_SUPPORTED"]
  }
}

Common field requirements:

  • email is required for all non-CH/LI destinations (except GB)
  • phone is required for GB destinations (international format: +44...)
  • houseNumber is required for NL destinations
  • stateCode is required for US/CA destinations

207 Multi-Status — partial batch failure​

Cause: In a batch request some shipments succeeded and others failed.

Fix: Check the failed array in the response for per-item fieldErrors. The success array contains created shipments with their parcel numbers and labels.

Label is empty / not printing​

Cause: printOptions.labelFormat mismatch with your printer.

Fix: Set labelFormat explicitly in your request:

  • "A4" — full A4 sheet (multiple labels per page, use labelStartPosition 1–4)
  • "A6" — thermal label printers

Parcel Shops​

Cause: No shops found within the default 5 km search radius, or the address could not be resolved.

Fix:

  1. Try providing both zipCode and city — the API falls back to postal code if the full address cannot be geocoded
  2. Remove service/type filters to widen the search
  3. Set hideClosed: false to include shops that may be temporarily closed

404 Not Found for parcel shop ID​

Cause: The shop ID does not exist or is no longer active.

Fix: Re-search by address or coordinates to get current shop IDs. Parcel shop IDs can change when shops close or reopen.

Tracking​

404 Not Found for parcel number​

Cause: Tracking data is not yet available or the parcel number is incorrect.

Fix:

  1. Verify the parcel number from the shipment creation response (success[].parcelNumber)
  2. Allow a few minutes after shipment creation for tracking to become available
  3. Ensure the parcel number format is correct (e.g., 05305000123456)

Collection Requests & Pickup Orders​

pickupDate rejected​

Cause: The date is in the past or incorrectly formatted.

Fix: Use yyyy-MM-dd format and ensure the date is at least tomorrow's date in the European timezone.

General​

HTTPS / SSL errors​

All API calls must use HTTPS. Self-signed certificates are not accepted in production.

Rate limiting (429 Too Many Requests)​

Implement exponential backoff in your application. Consider caching parcel shop data (it changes infrequently) to reduce API calls.

Still stuck?​

Contact DPD support and include:

  • The tracingId from the API response (or the full error response body)
  • The endpoint you called and approximate time of the request
  • Your integration environment (dev/staging/production)