API Error Documentation
This page provides a comprehensive guide to the most common API errors encountered when working. The errors are divided into categories based on their API type, including Generic API Errors, Xpress API Errors & eDC.
Each category includes detailed explanations of the error codes, their possible causes, and the steps you can take to resolve the issue.
Most Common API Errors
These errors are common across all APIs and usually relate to authentication, missing parameters, or incorrect requests.
_____________________________________________________________________________________________________________________________________________
401 - Unauthorized
Issue: The API request is not authenticated correctly.
Example of Incorrect Request:
{ "message": "Access denied",
"statusCode": 401 }
Possible Causes
Missing or invalid DSV-Subscription-Key.
Incorrect DSV User credentials (Password or user)
Invalid OAuth Bearer token.
Solution:
Include a valid API key in the request headers.
Validate User credentials or reset password.
Ensure the OAuth token is active.
_____________________________________________________________________________________________________________________________________________
403 - Forbidden
Issue: Access denied due to missing API role
Example of Incorrect Request:
{"code":403,"message":"
Access denied due to missing API role"}
Possible Causes
Missing API Role in myDSV
myDSV Account is inactive
Solution:
Contact API Suport to verify your account status
Email: developer.support@dsv.com
_____________________________________________________________________________________________________________________________________________
404 - Not Found
Issue: The request contains incorrect or missing parameters, which resulted in the resource not being found.
Example of Incorrect Request:
{"code":"E98","message":"
Not found booking:,"fields":null,"development":null}
Possible Causes
The bookingID, shipmentID, reference or other required parameters are missing or incorrect.
The referenced resource does not exist in the system.
There is a typo or formatting issue in the request payload.
Solution:
Double-check that all required parameters are present and correctly formatted.
Confirm that the booking or resource you are trying to access exists.
Refer to the API documentation for the correct structure and required fields.
_____________________________________________________________________________________________________________________________________________
500 - Internal Server Error
Issue: The server encountered an unexpected condition that prevented it from fulfilling the request.
Possible Causes
The request was sent to an incorrect or inactive endpoint.
Required headers or parameters are missing from the request.
The server experienced an internal failure while processing the request.
Solution:
Ensure that the request is sent to the correct and active endpoint.
Verify that all required headers and parameters are included and correctly formatted.
Check server logs for further details on the internal error and resolve any misconfigurations.
_____________________________________________________________________________________________________________________________________________
Generic API Errors
In this section, we cover common API errors that can occur across all Generic APIs. These errors generally relate to authentication issues, missing parameters, or incorrect requests. Understanding these errors and their solutions will help you troubleshoot and resolve issues quickly when interacting with any of our API services.
400 - Bad Request: Invalid Pickup Date
Issue: The pickup date must be today or a future date.
Possible Causes
The request contains a pickup date in the past.
Solution:Ensure the pickup date is today or in the future before submitting the request.
Example of Incorrect Request:
{ "code": "E99", "message": "general error",
"fields": [ { "name": "validationError", "message": "40257145990025696066 Pickup date should be same or after current date",
"code": "validationError"} ]}
Solution:
Ensure all required fields (pickupAddress, deliveryAddress, weight, dimensions) are included.
Validate that the locations are within supported regions.
400 - Bad Request: Autobook Disabled Due to Previous Errors
Issue: The autobooking process was disabled due to a previous error. The provided MDM is not assigned to the user.
Possible Causes
Attempted autobooking after a failure.
The specified MDM does not belong to the authenticated user.
Example of Incorrect Request:
{ "code": "E99",
"message": "general error", "fields": [ { "name": "validationError", "message": "Autobook disabled due to previous errors: 40257145990025696059", "code": "validationError" },
{ "name": "bookingError", "message": "The following mdm is not assigned to this user: '6400931700' ", "code": "bookingError" } ],
Solution:
Verify that autobooking is enabled before submitting the request.
Use an MDM that is correctly assigned to the user.
400 - Bad Request: Invalid Package Quantity
Issue: The request contains missing or invalid shipment details for rate comparison.
Possible Causes
The request does not include required fields such as pickupAddress, deliveryAddress, or weight.
The shipment details provided are outside the supported regions.
Example of Incorrect Request:
{ "code": "E99",
"message": "General Error",
"fields": [{ "name": "validationError", "message": "40257145990025696134 Package quantity must be present and positive", "code": "validationError" }],
"development": null }
Solution:
Ensure all required fields (pickupAddress, deliveryAddress, weight, dimensions) are included.
Validate that the locations are within supported regions.
400 - Bad Request: Missing Address details
Issue: The city/Addresline1/zipcode/Country/State field is missing from the address details.
Possible Causes
The request does not include required fields such as city/Addresline1/zipcode/Country/State in some of the included parties.
Include a valid city value in the address section of the request.
Example of Incorrect Request:
{ "code": "E99",
"message": "General Error",
"fields": [{ "name": "validationError", "message": "Autobook disabled due to previous errors: 40257145990025696097", "code": "validationError" },
{ "name": "bookingError", "message": "Address city is empty", "code":
"bookingError" } ], "development": null
}
Solution:
Include a valid value in the address section of the request.
400 - Bad Request: Unsupported Label Format
Issue: The request contains an invalid label format.
Possible Causes
The type field in the request contains an unsupported label format.
The request does not include the type field.
The value provided for type is misspelled or incorrectly formatted.
Example of Incorrect Request:
{ "type": "DOCX"}
Solution:
Use a supported format (PDF, ZPL, PNG).
403 - Forbidden: Unauthorized Shipment Access
Issue: The shipmentId does not belong to the requesting user.
Possible Causes
The shipmentId belongs to a different account or organization.
The API key or user role lacks the necessary permissions.
Example of Incorrect Request:
{ "shipmentId": "SH123456",
"status": "Pending" }
Solution:
Verify permissions with DSV support or API Support.
404 - Not Found: Document Not Available
Issue: The requested document does not exist.
Possible Causes
The documentId provided in the request does not exist in the system.
The document has been deleted or expired.
The document is not linked to any valid shipment.
Solution:
Ensure the documentId is valid and linked to a shipment.
415 - Unsupported Media Type: Incorrect File Format
Issue: The file format sent in the request is not supported by the API.
Possible Causes
The file format sent in the request is not in the list of supported types.
The Content-Type header is incorrect or missing.
The file is corrupted or improperly encoded.
Example of Incorrect Request:
Content-Type: text/plain
Solution:
Use a supported file format (PDF, JPEG).
404 - Not Found: Invoice Does Not Exist
Issue: The invoice reference is not found.
Possible Causes
The invoice reference provided does not exist in the database.
The invoice is linked to a different environment
The invoice has been deleted or archived.
Solution:
Ensure the invoice exists and matches the correct API environment. Contact API Support in case the invoice is missing.
400 - Bad Request: Invalid Shipment Data
Issue: Missing or incorrectly formatted shipment parameters.
Possible Causes
Required shipment parameters are missing from the request.
One or more shipment details are incorrectly formatted.
The request contains an invalid shipmentId or tracking number.
Solution:
Check the API schema for required fields and formats .............................
401 - Unauthorized: Missing OAuth Token
Issue: The request lacks a valid OAuth token.
Possible Causes
The request does not include a valid OAuth token in the headers.
The token provided has expired or is invalid.
The API key or authentication credentials are incorrect.
Solution:
Ensure authentication is included in the request headers.
_____________________________________________________________________________________________________________________________________________
XPress API Errors
This section details errors specific to the Xpress API, which includes functionalities like shipment booking, rate comparison, label retrieval, and shipment tracking. These errors have been carefully extracted from the official Xpress API documentation and verified with real system logs to provide accurate troubleshooting information.
400 - Bad Request: Invalid Booking Details
Issue: The booking request is missing required details or contains incorrect data.
Possible Causes
pickupDate is in the past.
shipmentType is not supported.
The declared weight exceeds allowed limits.
Example of Incorrect Request:
{
"pickupDate": "2023-02-10T09:00:00Z",
"shipmentType": "INVALID_TYPE",
"weight": 50000
}
(Date is in the past, shipmentType is invalid, and weight exceeds the limit)
Solution:
Use a valid pickupDate (future date).
Check the list of allowed shipment types.
Ensure the weight is within the maximum allowed range.
400 - Bad Request: Invalid Shipment Details
Issue: The request contains missing or invalid shipment details for rate comparison.
Possible Causes
The request does not include required fields such as pickupAddress, deliveryAddress, or weight.
The shipment details provided are outside the supported regions.
Example of Incorrect Request:
{
"pickupAddress": "",
"deliveryAddress": "Berlin, Germany",
"weight": 50
}
(Missing pickupAddress value)
Solution:
Ensure all required fields (pickupAddress, deliveryAddress, weight, dimensions) are included.
Validate that the locations are within supported regions.
400 - Bad Request: Invalid Shipment Query
Issue: The request contains an invalid shipment ID or tracking number.
Possible Causes
The shipmentId is not formatted correctly.
The tracking number does not belong to the requesting account.
Example of Incorrect Request:
{
"shipmentId": 12345
}
(Shipment ID should be a string, not a number)
Solution:
Use a properly formatted shipment ID.
Ensure the tracking number is correct.
404 - Not Found: Shipment ID Does Not Exist
Issue: The requested shipment ID does not exist or has no associated labels.
Possible Causes
The shipmentId is incorrect or has been deleted.
Labels were not generated for the shipment.
Example of Incorrect Request:
{
"shipmentId": "INVALID_ID"
}
(Missing pickupAddress value)
Solution:
Verify that the shipmentId exists.
Ensure that labels have been generated before requesting them.
_____________________________________________________________________________________________________________________________________________
eDC API Errors
This section outlines errors specific to the EDC API, which handles order creation, load plans, shipment tracking, and event logging. The errors listed here are based on the official EDC API documentation and are supported by real-world system logs for accurate troubleshooting.
400 - Bad Request: Invalid Load Plan Structure
Issue: The request contains an invalid load plan format.
Possible Causes
The request does not include shipmentId or loadPlanDetails.
The loadPlanDetails object is empty.
Example of Incorrect Request:
{
"shipmentId": "SH123456"
}
............................................................................................................................
Solution:
Ensure loadPlanDetails is included and correctly structured.
400 - Bad Request: Missing Required Fields
Issue: The order request is missing mandatory fields.
Possible Causes
The request does not include orderReference, pickupLocation, or deliveryLocation.
The orderDate is missing or incorrectly formatted.
Example of Incorrect Request:
{
"orderReference": "ORDER-12345",
"pickupLocation": "Copenhagen, Denmark"
}
(Missing deliveryLocation field)
Solution:
Ensure all required fields are included in the request.
Follow the correct date format (YYYY-MM-DDTHH:MM:SSZ).
404 - Not Found: No Shipments Match Criteria
Issue: No shipments were found for the given search criteria.
Possible Causes
The search filters do not match any existing records.
The requested time range is outside the available data.
Example of Incorrect Request:
{ "fromDate": "2020-01-01",
"toDate": "2020-01-02" }
Solution:
Adjust search criteria (e.g., expand the date range, remove strict filters).
400 - Bad Request: Invalid Event Type
Issue: The event type provided in the request is not recognized.
Possible Causes
The eventType does not match the API’s accepted values.
The event timestamp is missing or incorrect.
Solution:
Use only allowed event types (e.g., PICKUP, DELIVERY,
CUSTOMS_CLEARANCE).
Ensure eventTimestamp is in ISO 8601 format.
...................................................................................................................
415 - Unsupported Media Type: Incorrect File Format
Issue: The uploaded document format is not supported.
Possible Causes
The file type is not allowed (e.g., .docx instead of .pdf).
The request does not include a valid Content-Type header.
Incorrect Request (Headers:
Content-Type: text/plain
Corrected Request (Headers):
Content-Type: application/pdf
Solution:
Use only allowed formats (PDF, TIFF, JPEG).
Ensure the correct Content-Type header is set in the request.
403 - Forbidden: Unauthorized Access
Issue: The user does not have permission to access the requested booking.
Possible Causes
The API key does not have booking retrieval permissions.
The booking belongs to another account.
Incorrect Request (Headers):
DSV-Subscription-Key: incorrect_key
eDC User Account
Solution:
Verify API key permissions with eDC support.
Ensure the booking is linked to the correct account.