Common API Errors

This guide helps you understand the most common API errors across DSV APIs. Errors are grouped into general platform errors and API-specific examples so you can quickly identify the issue, understand the likely cause, and take the next troubleshooting step.

How to use this page: Start with Most Common Errors for status codes like 401, 403, 404, and 500. Then expand the API-specific sections if you are troubleshooting Booking, Tracking, Labels, Upload, Invoices, Visibility, Webhook, XPress, or SCM APIs.
Most Common Errors Generic API Errors XPress API Errors SCM API Errors Support

This page lists common errors returned by DSV APIs along with their meaning and possible resolution steps. Use the error code or message returned in the API response to quickly identify the issue.

Tip: Use Ctrl + F to search for the error code (for example: 400, 401, E99, validationError).

Most Common Errors
Common across multiple APIs
401 - Unauthorized
The API request is not authenticated correctly

What it means: The request could not be authenticated.

Possible causes:

  • Missing or invalid DSV-Subscription-Key
  • Invalid OAuth bearer token
  • Incorrect user credentials where applicable

What to check:

  • Make sure the subscription key belongs to the correct environment
  • Ensure the bearer token is active and not expired
  • Confirm the Authorization header is sent correctly
{ "message": "Access denied", "statusCode": 401 }
403 - Forbidden
Access denied due to missing access or permissions

What it means: The request is authenticated, but the user or application does not have access.

Possible causes:

  • Missing API role in myDSV
  • Inactive myDSV account
  • User does not have access to the requested booking or shipment

What to check:

  • Confirm the user has the correct API role
  • Check whether the account is active
  • Verify the shipment or booking belongs to the requesting organization
{ "code": 403, "message": "Access denied due to missing API role" }
404 - Not Found
The requested resource could not be found

What it means: The resource does not exist, is not available in that environment, or the request parameters are incorrect.

Possible causes:

  • Incorrect or missing bookingID, shipmentID, reference, invoice reference, or documentId
  • Typo or formatting issue in the request
  • Resource exists in another environment only

What to check:

  • Verify the ID or reference value
  • Confirm the resource exists in the same environment you are calling
  • Review the request structure against the API specification
{ "code": "E98", "message": "Not found booking:", "fields": null, "development": null }
500 - Internal Server Error
The server could not process the request successfully

What it means: The server encountered an unexpected issue while processing the request.

Possible causes:

  • Request sent to an incorrect or inactive endpoint
  • Missing required headers or parameters
  • Unexpected internal failure

What to check:

  • Make sure you are using the correct endpoint URL
  • Verify required headers and parameters are included
  • Retry only after validating the request structure
Generic API Errors
Examples across Booking, Labels, Tracking, Upload, Invoices, Visibility, and Webhook APIs
Error API Area Main Meaning
400 Booking / Labels / Visibility Validation issue, missing field, invalid value, or incorrect request structure
403 Tracking User does not have access to the shipment
404 Download / Invoices Requested document or invoice was not found
415 Upload Unsupported file type or incorrect Content-Type
401 Webhook Missing or invalid OAuth token
400 - Invalid Pickup Date API Booking
Pickup date must be today or in the future
  • Cause: Pickup date is in the past
  • Resolution: Use today's date or a future date
{ "code": "E99", "message": "general error", "fields": [ { "name": "validationError", "message": "Pickup date should be same or after current date", "code": "validationError" } ] }
400 - Autobook Disabled / MDM Not Assigned API Booking
Autobooking blocked or MDM does not belong to the user
  • Cause: Autobooking was disabled due to earlier errors
  • Cause: The provided MDM is not assigned to the authenticated user
  • Resolution: Check autobooking status and use an MDM mapped to the user
{ "code": "E99", "message": "general error", "fields": [ { "name": "validationError", "message": "Autobook disabled due to previous errors", "code": "validationError" }, { "name": "bookingError", "message": "The following mdm is not assigned to this user", "code": "bookingError" } ] }
400 - Invalid Package Quantity API Booking
Package quantity must be present and positive
  • Cause: Missing or non-positive package quantity
  • Resolution: Include a valid positive quantity in the shipment details
{ "code": "E99", "message": "General Error", "fields": [ { "name": "validationError", "message": "Package quantity must be present and positive", "code": "validationError" } ], "development": null }
400 - Missing Address Details API Booking
Address field such as city, addressLine1, zipCode, country, or state is missing
  • Cause: One or more required address fields are empty
  • Resolution: Provide complete address details for all required parties
{ "code": "E99", "message": "General Error", "fields": [ { "name": "validationError", "message": "Autobook disabled due to previous errors", "code": "validationError" }, { "name": "bookingError", "message": "Address city is empty", "code": "bookingError" } ], "development": null }
400 - Unsupported Label Format API Labels
Requested label format is not supported
  • Cause: Unsupported or missing type field
  • Resolution: Use a supported format such as PDF, ZPL, or PNG
{ "type": "DOCX" }
403 - Unauthorized Shipment Access API Tracking
The shipment does not belong to the requesting user or organization
  • Cause: Shipment belongs to a different account or organization
  • Cause: API role or permissions are insufficient
  • Resolution: Verify shipment visibility and permissions with support
{ "shipmentId": "SH123456", "status": "Pending" }
404 - Document Not Available API Download
Requested document was not found
  • Cause: Invalid documentId
  • Cause: Document was deleted, expired, or not linked properly
  • Resolution: Verify the documentId and confirm it belongs to a valid shipment
415 - Unsupported Media Type API Upload
File type or Content-Type header is not supported
  • Cause: File type is not supported
  • Cause: Missing or incorrect Content-Type header
  • Resolution: Use a supported format such as PDF or JPEG and send the correct Content-Type
Content-Type: text/plain
404 - Invoice Does Not Exist API Invoices
Invoice reference could not be found
  • Cause: Invalid invoice reference
  • Cause: Invoice exists in another environment
  • Cause: Invoice was archived or removed
  • Resolution: Confirm the invoice reference and environment
400 - Invalid Shipment Data API Visibility
Shipment fields are missing or incorrectly formatted
  • Cause: Missing required shipment parameters
  • Cause: Invalid shipmentId or tracking number format
  • Resolution: Validate the request body against the API schema
401 - Missing OAuth Token API Webhook
Authentication token is missing, expired, or invalid
  • Cause: No OAuth token in the request headers
  • Cause: Expired or invalid token
  • Resolution: Send a valid bearer token in the Authorization header
XPress API Errors
Booking, Quote, Tracking, and Label-related XPress issues
400 - Invalid Booking Details API Booking XPress
Booking request contains unsupported or invalid values
  • Cause: pickupDate is in the past
  • Cause: shipmentType is not supported
  • Cause: Declared weight exceeds allowed limits
  • Resolution: Use valid future date, allowed shipmentType, and supported weight
{ "pickupDate": "2023-02-10T09:00:00Z", "shipmentType": "INVALID_TYPE", "weight": 50000 }
400 - Invalid Shipment Details API Quote
Required shipment details for rate comparison are missing or invalid
  • Cause: Missing pickupAddress, deliveryAddress, weight, or dimensions
  • Cause: Locations fall outside supported regions
  • Resolution: Complete all required shipment details and validate locations
{ "pickupAddress": "", "deliveryAddress": "Berlin, Germany", "weight": 50 }
400 - Invalid Shipment Query API Tracking XPress
Shipment ID or tracking number is invalid
  • Cause: shipmentId format is incorrect
  • Cause: Tracking number does not belong to the requesting account
  • Resolution: Use properly formatted IDs and verify account ownership
{ "shipmentId": 12345 }
404 - Shipment ID Does Not Exist API Booking XPress
Shipment was not found or has no labels
  • Cause: shipmentId is incorrect or no longer exists
  • Cause: Labels were not generated for the shipment
  • Resolution: Verify the shipment ID and make sure labels exist before retrieving them
{ "shipmentId": "INVALID_ID" }
SCM API Errors
Orders, load plans, shipments, events, eDocs, and bookings
400 - Invalid Load Plan Structure SCM Load Plan
Load plan object is missing or incomplete
  • Cause: shipmentId or loadPlanDetails is missing
  • Cause: loadPlanDetails is empty
  • Resolution: Include a properly structured loadPlanDetails object
{ "shipmentId": "SH123456" }
400 - Missing Required Fields SCM Orders
Mandatory order fields are missing
  • Cause: orderReference, pickupLocation, or deliveryLocation is missing
  • Cause: orderDate is missing or incorrectly formatted
  • Resolution: Include all mandatory fields and follow the expected date format
{ "orderReference": "ORDER-12345", "pickupLocation": "Copenhagen, Denmark" }
404 - No Shipments Match Criteria SCM Shipments
Search filters returned no matching results
  • Cause: Filters are too strict
  • Cause: Date range falls outside available data
  • Resolution: Expand the date range or relax the search filters
{ "fromDate": "2020-01-01", "toDate": "2020-01-02" }
400 - Invalid Event Type SCM Events
Provided event type is not supported
  • Cause: eventType is not one of the accepted values
  • Cause: eventTimestamp is missing or not in ISO 8601 format
  • Resolution: Use only allowed event types and valid timestamps
415 - Unsupported Media Type SCM eDoc
Uploaded file type or Content-Type is not allowed
  • Cause: Unsupported format such as .docx
  • Cause: Incorrect Content-Type header
  • Resolution: Use allowed formats such as PDF, TIFF, or JPEG and set the right Content-Type
Incorrect: Content-Type: text/plain Correct: Content-Type: application/pdf
403 - Unauthorized Access SCM Bookings
User does not have permission to access the booking
  • Cause: API key does not have booking retrieval permissions
  • Cause: Booking belongs to another account
  • Resolution: Verify access and key permissions with support
DSV-Subscription-Key: incorrect_key
Support
What to include when reporting an API error

For support, contact: developer.support@dsv.com

Please include:

  • API name and environment (Demo / Production)
  • Endpoint and method used
  • Timestamp of the failed request
  • Response body / error message
  • Reference, booking ID, shipment ID, or invoice reference where relevant
  • A sanitized request sample if possible