Shipment API Feedback and Error Handling

Introduction

When sending declarations to the Shipment JSON API, the API returns feedback regarding the submitted dataset. This feedback helps identify validation issues, formatting errors, duplicate references, and other processing problems.

Understanding and correctly handling these responses is essential for maintaining stable integrations and minimizing operational disruptions.

Visibility of API Feedback

To minimize operational disruptions, it is strongly recommended that the integrating application displays Shipment API feedback directly to end users.

Users who can view validation messages immediately are often able to resolve issues themselves without involving their IT department or the Stratech Service Desk. This significantly reduces resolution times and prevents unnecessary delays in declaration processing.

General POST Response Rules

Important: A status code 200 does not automatically mean that the submitted dataset has been accepted or processed successfully. Always review the response body for validation messages, warnings, or processing errors.

Common HTTP Status Codes

Recommended Implementation

The integrating application should:

• Display validation messages returned by the Shipment API directly to the user.

• Store and log the complete API response.

• Clearly distinguish between connection errors and validation errors.

• Allow users to identify which declaration generated the error.

• Display the related ApplicationReferenceId whenever possible.

Benefits

• Faster issue resolution.

• Reduced dependency on IT departments.

• Reduced dependency on Stratech support.

• Less operational downtime.

• Faster correction and resubmission of declarations.When Detailed Error Messages Are Not Available

If the application does not display the detailed API response, troubleshooting becomes considerably more difficult.
In these situations, the submitted JSON dataset must be provided for investigation.

The following information should be supplied:

• The complete JSON request submitted to the Shipment API.

• The API response returned by Shipment, if available.

• The related ApplicationReferenceId.

• The date and time of submission.

• Screenshots or any additional error information shown by the application.

Without access to the submitted JSON payload, it may not be possible to determine the root cause of a validation or processing issue.

Best Practice

Applications integrating with the Shipment API should be designed to expose API feedback directly to operational users. This enables most data-related issues to be resolved immediately by the user creating the declaration, reducing disruptions and improving process efficiency.

Error Examples

Duplicate ApplicationReferenceId

• Error: The following ApplicationReferenceIds have already been used before: REF_123456789

• Cause: The supplied ApplicationReferenceId has already been used in a previous submission.

• Action: Provide a new unique ApplicationReferenceId.

Important: Every submitted dataset must contain a unique ApplicationReferenceId, regardless of whether previous submissions were successful or unsuccessful.

Container Shipment Validation Error

• Error: The declaration has 'TransportEquipment_Number' set but the related 'IsContainerShipment' is not set properly for applicationReference id: REF_123456789.

• Cause: Container information has been provided while the following setting is configured: "isContainerShipment": false

• Action: When container information is included in the declaration, configure:

  • "isContainerShipment": true

  • Alternatively, remove all container information from the dataset.
    

AddressDescription Validation Error

•  Error {  "Consignee.AddressDescription": [    "The field AddressDescription must match the regular expression '^.{0,50}(\\n.{0,50}){0,5}$'."  ]

• Cause:  Incorrect line break notation has been used within the address field.
  Incorrect: "addressDescription": "Company Name B.V./nStreet Name 123/n1234 AB City"
  Correct: "addressDescription": "Company Name B.V.\nStreet Name 123\n1234 AB City"

• Action: Use \n as line separators instead of /n.

Generic Import Error

• Error: An error occured while importing this declaration. Meldcode: XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX

• Cause: An unexpected error occurred during declaration processing.

• Action: Forward the following information to the Stratech Service Desk:

  • Error message.

  • Meldcode.

  • Timestamp of submission.

  • ApplicationReferenceId.

• This information is required for further investigation.

Empty String Validation Errors

• Error DmsExportDeclarations[0].DeclarationData.Warehouse.Type": [      "The value of Type may not be shorter than 1 character." ],

• Cause Empty string values ("") have been supplied for fields that require either a valid value or no value at all.

  • Example:   
    
    "warehouse": {
        "type": "",
        "licensenumber": ""
    }

• Action: Remove the fields entirely or provide: null instead of an empty string.
  

  • Correct Example
    
    "warehouse": {
        "type": null,
        "licensenumber": null
    }

  • Alternatively, omit the fields completely.

Postal Code Format Error (BG9018)

• Error  "GoodsShipment.Consignment.GoodsLocation.Address.PostCode: BG9018: IF <Type of Identification> = 'T'    Attribute to be composed as follows:
      - Position 1-4: numeric part of postal code
      - Position 5: blank
      - Position 6-7: two uppercases
      (A2)(ErrorCode RegularExpressionValidator)"  ]}

• Cause: The postal code does not comply with the required format.

  • Required format:

    • Position 1-4: Four digits

    • • Position 5: One space

    • Position 6-7: Two uppercase letters

  • Incorrect "postalCode": "1234AB"

  • Correct "postalCode": "1234 AB"

• Action: Ensure that postal codes are supplied in the required format.

Credit Bundle Exhausted

• Error: "Submitting is not possible because the credit bundle has been exhausted. Please purchase a new bundle."

  • Cause: The available declaration credits have been exhausted or the purchased credit bundle has expired.
  • Action: Purchase a new declaration bundle before submitting additional declarations.