Validation errors in MO APIs

Content

Sequence for Submission - Synchronous and Asynchronous Responses
Synchronous Validation Errors
Asynchronous Validation Errors
Incomplete documentation
- Document Status Format
- Document status INCOMPLETE

Sequence for Submission - Synchronous and Asynchronous Responses

Also review this documentation: https://toll.github.io/api/mo-vei-EN.html#hvordanSende, this applies to all modes of transport.

In general, the submission of information works like this: a party sends a notification (POST) and receives a reference (requestId). By using the received reference, the party can query (GET) the result of the submission and, upon success, receive a permanent reference to the notification issued by Norwegian Customs. This is done at a separate endpoint (/validation-status) in the query API linked further down on this page. These services are asynchronous, so one must query repeatedly until a response is received. The validation response is usually available within 1 to 2 seconds, but it may take longer in some cases.
The query is made to the /validation-status endpoint, which will return the permanent reference, a Master Reference Number (MRN), upon success, along with a list of validation errors if they exist.

Example of a submission sequence for consignment (house consignment). The pattern is the same for other notifications, such as the master consignment and transport.

See caption — Figure: Sequence for submission of a notification for a house consignment

The MRN is used when notifications need to be updated or canceled (put/delete) to refer to previously submitted notifications. The validation endpoint can also return a list of document statuses to indicate missing information; see https://toll.github.io/api/mo-kodeverk-EN.html#incompleteDocumentationReason. The recommended method for submission is for the party to send all notifications for creation (POST) that are relevant and then wait 1-2 seconds before querying for validation (query API).

For example: If there are 500 house consignments for a master consignment in a transport, submit all 500 consignment notifications (POST), wait a couple of seconds, then request validation, the MRN and status for all 500 notifications is returned. If a status 404 is received when calling the validation endpoint, wait a little longer and query again. It is recommended to create an algorithm that makes repeated attempts until the validation response is received.

Synchronous Validation Errors

Synchronous validation errors (via HTTP) are returned as a response with status code 400 from the API. The reason for the validation error is returned as the content (body) of the response. When synchronous validation errors occur, the submission is immediately rejected and not processed further until the error(s) are corrected and resubmitted. If there are no synchronous validation errors, the response will have a status code 202 and contain a "requestId" field, which is then used to check for asynchronous validation errors during further processing.

Content Format of Synchronous Validation Errors

Validation errors are returned as one or more objects in a "validationErrors" list. The content of the list consists of one or more objects that indicate which fields caused the validation error, specified in the "field" field, and the reason for the error, specified in the "error" field.

        {
          "validationErrors": [
            {
              "field": "${fieldWithErrorOne}",
              "error": "${validationErrorCauseOne}"
            },
            {
              "field": "${fieldWithErrorTwo}",
              "error": "${validationErrorCauseTwo}"
            }
          ]
        }

Missing or Blank ("") Required Fields

Response

{
  "validationErrors": [
    {
      "field": "${fieldname}",
      "error": "must not be null"
    },
    {
      "field": "${fieldname}",
      "error": "must not be blank"
    }
  ]
}

Cause

Fields that are required are missing or contain empty values. Fields that cannot have empty values will return "must not be blank" whether they are missing or empty. All other required fields will return "must not be null" if they are missing.

Correction

The field is required ("must not be null"), or must be present and have a value ("must not be blank").

Incorrect date/time format

Response

{
  "validationErrors": [
    {
      "field": "${fieldname}",
      "error": "invalid ISO-8601 instant in UTC (yyyy-MM-ddTHH:mm:ssZ)"
    }
  ]
}

Cause

Date and time fields are in the wrong format. They must follow the ISO-8601 standard, which means they should be in the format: yyyy-MM-ddTHH:mm:ssZ.

Correction

Change the format to follow the ISO-8601 standard in the format yyyy-MM-ddTHH:mm:ssZ.

Incorrect Field Size – Numeric Values

Response

{
  "validationErrors": [
    {
      "field": "${fieldname}",
      "error": "numeric value out of bounds (<${maxInteger} digits>.<${maxDecimalNumber} digits> expected)"
    }
  ]
}

Cause

A numeric value has been provided that exceeds the maximum number of digits allowed before or after the decimal point ("."). If only integers are allowed, the number of digits after the decimal point (".", i.e., maxDecimalNumber) should be 0.

Correction

Adjust the number to be within the maximum number of integer digits (maxInteger value) and the maximum number of decimal digits (maxDecimalNumber value).

Incorrect Field Size – String (Text)

Response

{
  "validationErrors": [
    {
      "field": "${fieldname}",
      "error": "size must be between ${minLength} and ${maxLength}"
    }
  ]
}

Cause

The content of the field has exceeded the maximum number of characters or contains fewer than the minimum number of characters.

Correction

Adjust the content to be within the minimum and maximum size limits.

At Least One of the Fields Must Be Provided

Response

{
  "validationErrors": [
    {
      "field": "${fieldname}",
      "error": "At least one of the following fields should be non null: [${fieldOne}, ${fieldTwo}]"
    }
  ]
}

Cause

In some cases, at least one of several fields must be provided. The object specified by in (fieldname) must contain a value in at least one of the specified fields.

Correction

Ensure that at least one of the specified fields is provided and has a valid value in the object.

Must be one of (required)

Response

{
  "validationErrors": [
    {
      "field": "${fieldname}",
      "error": "Must be one of [${valueOne}, ${valueTwo}]"
    }
  ]
}

Cause

The field (fieldname) must be submitted and can only have one of the specified values.

Correction

Submit the field with one of the required values (e.g., valueOne ...).

Asynchronous Validation Errors

If a submission does not have any validation errors that lead to immediate rejection (synchronous validation errors), it will be processed further. However, validation errors may still occur later, during the processing. These errors will be returned in response to a call to the corresponding "/validation-status" endpoint once the processing is complete. Validation errors will be associated with the "requestId" value received in the original submission and returned as asynchronous validation errors.

Content Format for Asynchronous Validation Errors

If validation errors are found once asynchronous validation is complete, the "/validation-status" endpoint will return an HTTP code 202 with content where the "status" field has the value "FAILURE".
Validation errors are returned as one or more objects in a list called "validationErrorList". The content of the list consists of objects that indicate the path to the field(s) that caused the validation error, specified in the "pointer.messageElementPath" field, and the cause of the error is specified in the "description" field.

Until the processing is complete, the response from the endpoint will return an HTTP code 404.

If there are no validation errors and the submission is successful, the "status" field will have the value "SUCCESS".

{
  "status": "FAILURE",
  "requestId": "${requestIdForSubmission}",
  "notificationDate": "${dateTimeResultWasReady}",
  "validationErrorList": [
    {
      "description": "${validationErrorCauseOne}",
      "pointer": {
        "messageElementPath": "${pathToFieldWithErrorOne}"
      }
    },
    {
      "description":  "${validationErrorCauseTwo}",
      "pointer": {
        "messageElementPath": "${pathToFieldWithErrorTwo}"
      }
    }
  ]
}

The Field Must Have a Value Specified by the Code List

Response

{
  "status": "FAILURE",
  "requestId": "${requestIdForSubmission}",
  "notificationDate": "${dateTimeResultWasReady}"
  "validationErrorList": [
    {
      "description": "Invalid code. Expected codes are one of [${codeOne}, ${codeTwo}]",
      "pointer": {
        "messageElementPath": "${pathToFieldWithError}"
      }
    }
  ]
}

Cause

The field specified in "messageElementPath" had a value not found in the code list (table of valid values). One of the values from the code list, as indicated by ["codeOne", "codeTwo", ...], is required for the field.

Correction

Change the field to have a value that corresponds to a valid code list value required for the field. Resubmit the request. Use the new "requestId" received for the new submission and verify that asynchronous validation returns the "status" field with the value "SUCCESS" once the new processing is complete.

Invalid Country Code

Response

{
  "status": "FAILURE",
  "requestId": "${requestIdForSubmission}",
  "notificationDate": "${dateTimeResultWasReady}"
  "validationErrorList": [
    {
      "description": "Country is invalid",
      "pointer": {
        "messageElementPath": "${pathToFieldWithError}"
      }
    }
  ]
}

Cause

The field specified in "messageElementPath" has a country code that was not found among the valid ISO-3166 Alpha-2 codes.

Correction

Change the field to use a valid ISO-3166 Alpha-2 code. Resubmit the request. Use the new "requestId" received for the new submission and verify that asynchronous validation returns the "status" field with the value "SUCCESS" once the new processing is complete.

Invalid MRN Format for the Specified Export Type

Response

{
  "status": "FAILURE",
  "requestId": "${requestIdForSubmission}",
  "notificationDate": "${dateTimeResultWasReady}"
  "validationErrorList": [
    {
      "description": "Invalid MRN format for export of type ${typeOfExport}",
      "pointer": {
        "messageElementPath": "consignmentHouseLevel.exportFromEU[${indexInList}].exportId"
      }
    }
  ]
}

Cause

The MRN for the "exportId" field specified in "messageElementPath" is provided in a format that is invalid for the specified export type ("typeOfExport").

Correction

Change the field's value to use a valid MRN format. Resubmit the request. Use the new "requestId" received for the new submission and verify that asynchronous validation returns the "status" field with the value "SUCCESS" once the new processing is complete.

Road Transport Only (road-API): Export of type AES_EXPORT was not found or has incorrect status in AES

Response

{
  "status": "FAILURE",
  "requestId": "${requestIdForSubmission}",
  "notificationDate": "${dateTimeResultWasReady}"
  "validationErrorList": [
    {
      "description": "Export of type AES_EXPORT is not found or has wrong status in AES.",
      "pointer": {
        "messageElementPath": "consignmentHouseLevel.exportFromEU[${indexInList}].exportId"
      }
    }
  ]
}

Cause

The export is of type AES_EXPORT, but the exportId was not found or has an incorrect status in AES. In addition to there being no export declaration with the specified ID, other possible causes include:

The export declaration exists but has not been released from the departure customs office
The export declaration exists but has already been registered for export.

Correction

Verify and, if necessary, correct the exportId to ensure it is correct and has the appropriate status in AES. Resubmit the request. Use the new requestId received for the new submission and verify that asynchronous validation returns the "status" field with the value "SUCCESS" once the new processing is complete.

If a value indicating the procedure the consignment was subjected to before crossing the border into Norway ("outgoing procedure") is specified, it must be one of the codes allowed in the code list

Response

{
  "status": "FAILURE",
  "requestId": "${requestIdForSubmission}",
  "notificationDate": "${dateTimeResultWasReady}"
  "validationErrorList": [
    {
      "description": "When field is provided, it has to be one of ${outgoingProcedureCodes}",
      "pointer": {
        "messageElementPath": "consignmentHouseLevel.importProcedure.outgoingProcedure"
      }
    }
  ]
}

Cause

The value for the outgoingProcedure field was not found in the OutgoingProcedure code list: https://toll.github.io/api/mo-kodeverk-EN.html#outgoingprocedure.

Correction

Change the value to one of the values available in the OutgoingProcedure code list. Resubmit the request. Use the new requestId received for the new submission and verify that asynchronous validation returns the "status" field with the value "SUCCESS" once the new processing is complete.

If a value is provided in a field using un location codes ("UNLOCODE"), it must be one of the values found in the CL144 UNLOCODE code list

Response

{
  "status": "FAILURE",
  "requestId": "${requestIdForSubmission}",
  "validationErrorList": [
    {
      "description": "Invalid code. Expected valid UNLOCODE",
      "pointer": {
        "messageElementPath": "${pathToFieldWithError}"
      }
    }
  ]
}

Cause

Several fields in the notifications require a value based on the UN Location Codes, "UNLOCODE". The field specified in "messageElementPath" contains a submitted value that was not found in the CL144 UNLOCODE code list.

Correction

Change the value to one of the values available in the CL144 UNLOCODE code list. Resubmit the request. Use the new requestId received for the new submission and verify that asynchronous validation returns the "status" field with the value "SUCCESS" once the new processing is complete.

Cannot submit exportFromEu list if the procedure the consignment was subjected to until crossing the border into Norway ("outgoing procedure") is transit (TRA)

Response

{
  "status": "FAILURE",
  "requestId": "${requestIdForSubmission}",
  "notificationDate": "${dateTimeResultWasReady}"
  "validationErrorList": [
    {
      "description": "Field cannot have values when consignmentHouseLevel.importProcedure.outgoingProcedure is TRA",
      "pointer": {
        "messageElementPath": "consignmentHouseLevel.exportFromEU"
      }
    }
  ]
}

Cause

If the procedure the consignment was subjected to until crossing the border into Norway (in the outgoingProcedure field) has the value TRA (for transit), you cannot submit a reference to export from the EU (exportFromEU).

Correction

Remove exportFromEU from the import procedure or change the outgoingProcedure. Resubmit the request. Use the new requestId received for the new submission and verify that asynchronous validation returns the "status" field with the value "SUCCESS" once the new processing is complete.

If neither address nor location is specified, UN location code ("UNLOCODE") is required

Response

{
  "status": "FAILURE",
  "requestId": "${requestIdForSubmission}",
  "validationErrorList": [
    {
      "description": "If location AND address is not provided, then unloCode is required",
      "pointer": {
        "messageElementPath": "consignmentHouseLevel.placeOfDelivery.unloCode"
      }
    }
  ]
}

Cause

The object specified in "messageElementPath" has neither an "address" nor a "location" provided. In this case, the "unloCode" field must be provided and have a value for this object. This applies to the "placeOfLoading", "placeOfUnloading", "placeOfAcceptance", "placeOfDelivery".

Correction

Add a valid "unloCode" or, alternatively, add an "address" and/or "location" to the object. Resubmit the request. Use the new "requestId" received for the new submission and verify that asynchronous validation returns the "status" field with the value "SUCCESS" once the new processing is complete.

Reference to transit ("typeOfReference" equal to "N820") refers to a transit that does not have a valid status

Response

{
  "status": "FAILURE",
  "requestId": "${requestIdForSubmission}",
  "notificationDate": "${dateTimeResultWasReady}"
  "validationErrorList": [
    {
      "description": "Document with typeOfReference N820 contains a referenceNumber in wrong state",
      "pointer": {
        "messageElementPath": "${pathToFieldWithError}"
      }
    }
  ]
}

Cause

A reference to a transit has been provided where the type of reference is "N820" (typeOfReference equal to "N820"). This transit is not in the correct status. The requirement for correct status in this context is that the transit declaration must include a declared NO border crossing customs office and NO destination customs office, and the transit must be released from the departure customs office.

The document of type N820 specified in "messageElementPath" has the wrong status in the transit system.

Correction

Check that the transit declaration is in compliance with the description above.
Resubmit the request. Use the new "requestId" received for the new submission and verify that asynchronous validation returns the "status" field with the value "SUCCESS" once the new processing is complete.

VOEC goods item ("goodsItem") has a value over NOK 3,000, therefore an import declaration must be used instead

Response

{
  "status": "FAILURE",
  "requestId": "${requestIdForSubmission}",
  "notificationDate": "${dateTimeResultWasReady}"
  "validationErrorList": [
    {
      "description": "When item value exeedes NOK 3000, a regular import-declaration have to be submitted",
      "pointer": {
        "messageElementPath": "${pathToFieldWithError}"
      }
    }
  ]
}

Cause

VOEC has a maximum value per item of NOK 3,000. The "goodsItem" with the specified VOEC number ("vatIdentificationNumber") has a stated value per item ("itemAmountInvoicedVOEC") exceeding the maximum limit of NOK 3,000.

Correction

Create a regular import declaration for the item(s) and use this instead. Note that if one or more of the items purchased by the recipient has a value over NOK 3,000, all items will need to be cleared through customs in the usual manner. Refer to the guidance at Skatteetaten on VOEC.
Resubmit the request. Use the new "requestId" received for the new submission and verify that asynchronous validation returns the field "status" with the value "SUCCESS" once the new processing is complete.

No valid permissions found for the VOEC number specified on the VOEC "goodsItem"

Response

{
  "status": "FAILURE",
  "requestId": "${requestIdForSubmission}",
  "notificationDate": "${dateTimeResultWasReady}"
  "validationErrorList": [
    {
      "description": "Unknown vatIdentificationNumber",
      "pointer": {
        "messageElementPath": "${pathToFieldWithError}"
      }
    }
  ]
}

Cause

No valid VOEC permissions are found for the VOEC number ("vatIdentificationNumber") specified on the VOEC goods item ("goodsItem"). The VOEC number provided cannot be verified as valid. This may be due to an incorrect VOEC number or the expiration of the VOEC number's validity.

Correction

Change the VOEC number to a valid one. If a valid VOEC number cannot be obtained, the goods must be declared using a standard import declaration.
Resubmit the request. Use the new "requestId" received for the new submission and verify that asynchronous validation returns the field "status" with the value "SUCCESS" once the new processing is complete.

Can't send a list with VOEC item lines ("goodsItem") if the selected customs procedure ("importProcedure") for the consignment is not VOEC ("IMMEDIATE_RELEASE_VOEC")

Response

If consignmentHouseLevel.importProcedure.importProcedure is not IMMEDATE_RELEASE_VOEC, should not be provided.

{
  "status": "FAILURE",
  "requestId": "${requestIdForSubmission}",
  "notificationDate": "${dateTimeResultWasReady}"
  "validationErrorList": [
    {
      "description": "If consignmentHouseLevel.importProcedure.importProcedure is not IMMEDATE_RELEASE_VOEC, should not be provided.",
      "pointer": {
        "messageElementPath": "consignmentHouseLevel.goodsItem"
      }
    }
  ]
}

Cause

VOEC item lines ("goodsItem" list) cannot be submitted unless the customs procedure for the consignment ("importProcedure") is VOEC (has the value "IMMEDIATE_RELEASE_VOEC"

Correction

Remove the "goodsItem" list or set "importProcedure" to "IMMEDIATE_RELEASE_VOEC". Resubmit with the new "requestId" received and verify that asynchronous validation returns "status" with the value "SUCCESS" once processing is complete.

The code for the customs office referenced is invalid

Response

{
  "status": "FAILURE",
  "requestId": "${requestIdForSubmission}",
  "notificationDate": "${dateTimeResultWasReady}"
  "validationErrorList": [
    {
      "description": "Must be a valid customs office",
      "pointer": {
        "messageElementPath": "customsOfficeOfFirstEntry.referenceNumber"
      }
    }
  ]
}

Cause

The reference number provided for "customsOfficeOfFirstEntry" does not correspond to a valid customs office. Use the CL141 Customs office reference number from the code list https://toll.github.io/api/mo-kodeverk-EN.html#cl141

Correction

Provide a valid reference number for a customs office. Resubmit with the new "requestId" received and verify that asynchronous validation returns "status" with the value "SUCCESS" once processing is complete.

The originally required field "scheduledDateAndTimeOfArrival" is required for the transport notification

Response

{
  "status": "FAILURE",
  "requestId": "${requestIdForSubmission}",
  "notificationDate": "${dateTimeResultWasReady}"
  "validationErrorList": [
    {
      "description": "scheduledDateAndTimeOfArrival should be present",
      "pointer": {
        "messageElementPath": "transport.scheduledDateAndTimeOfArrival"
      }
    }
  ]
}

Cause

The "scheduledDateAndTimeOfArrival" field must always be included in the transport object.

Correction

Add the "scheduledDateAndTimeOfArrival" field with a valid value to the transport object. Resubmit with the new "requestId" received and verify that asynchronous validation returns "status" with the value "SUCCESS" once processing is complete.

The "scheduledDateAndTimeOfArrival" field cannot be set more than one year in advance

Response

{
  "status": "FAILURE",
  "requestId": "${requestIdForSubmission}",
  "notificationDate": "${dateTimeResultWasReady}"
  "validationErrorList": [
    {
      "description": "scheduledDateAndTimeOfArrival cannot be more than one year into the future",
      "pointer": {
        "messageElementPath": "transport.scheduledDateAndTimeOfArrival"
      }
    }
  ]
}

Cause

The "scheduledDateAndTimeOfArrival" field cannot be set more than one year in advance.

Correction

Change the "scheduledDateAndTimeOfArrival" field to a date that is less than one year in advance. Resubmit with the new "requestId" received and verify that asynchronous validation returns "status" with the value "SUCCESS" once processing is complete.

Feltet for estimert ankomsttid ("estimatedDateAndTimeOfArrival") er påkrevd på melding om transport

Response

{
  "status": "FAILURE",
  "requestId": "${requestIdForSubmission}",
  "notificationDate": "${dateTimeResultWasReady}"
  "validationErrorList": [
    {
      "description": "estimatedDateAndTimeOfArrival should be present",
      "pointer": {
        "messageElementPath": "transport.estimatedDateAndTimeOfArrival"
      }
    }
  ]
}

Cause

The field for estimated arrival time "estimatedDateAndTimeOfArrival" must always be included in the transport object.

Correction

Add the field "estimatedDateAndTimeOfArrival" with a valid value to the transport object. Resubmit. Use the new "requestId" received in return for the new submission and verify that the asynchronous validation for this returns the field "status" with the value "SUCCESS" when the new processing is complete.

Cannot provide an estimated arrival time ("estimatedDateAndTimeOfArrival") that is in the past

Response

{
  "status": "FAILURE",
  "requestId": "${requestIdForSubmission}",
  "notificationDate": "${dateTimeResultWasReady}"
  "validationErrorList": [
    {
      "description": "estimatedDateAndTimeOfArrival has already passed",
      "pointer": {
        "messageElementPath": "transport.estimatedDateAndTimeOfArrival"
      }
    }
  ]
}

Cause

The time specified for the estimated arrival time ("estimatedDateAndTimeOfArrival") must be in the future.

Correction

Change "estimatedDateAndTimeOfArrival" to a time in the future. Resubmit. Use the new "requestId" received in return for the new submission and verify that the asynchronous validation for this returns the field "status" with the value "SUCCESS" when the new processing is complete.

The time specified for the estimated arrival time ("estimatedDateAndTimeOfArrival") cannot be more than one year in the future

Response

{
  "status": "FAILURE",
  "requestId": "${requestIdForSubmission}",
  "notificationDate": "${dateTimeResultWasReady}"
  "validationErrorList": [
    {
      "description": "estimatedDateAndTimeOfArrival cannot be more than one year into the future",
      "pointer": {
        "messageElementPath": "transport.estimatedDateAndTimeOfArrival"
      }
    }
  ]
}

Cause

The time specified for the estimated arrival time ("estimatedDateAndTimeOfArrival") cannot be more than one year in the future.

Correction

Change the "estimatedDateAndTimeOfArrival" to a time less than one year in the future. Resubmit. Use the new "requestId" received in return for the new submission and verify that the asynchronous validation for this returns the field "status" with the value "SUCCESS" when the new processing is complete.

Road and rail only: Cannot provide a conveyanceReferenceNumber if modeOfTransportCode has a specified value

Response

{
  "status": "FAILURE",
  "requestId": "${requestIdForSubmission}",
  "notificationDate": "${dateTimeResultWasReady}"
  "validationErrorList": [
    {
      "description": "transport.activeBorderTransportMeans.modeOfTransportCode is ${value}, then this field should not be provided",
      "pointer": {
        "messageElementPath": "transport.activeBorderTransportMeans.conveyanceReferenceNumber"
      }
    }
  ]
}

Cause

With the code specified for modeOfTransportCode, it is not permitted to send a value for conveyanceReferenceNumber.

Correction

Remove conveyanceReferenceNumber or change the specified modeOfTransportCode. Resubmit. Use the new "requestId" received in return for the new submission and verify that the asynchronous validation for this returns the field "status" with the value "SUCCESS" when the new processing is complete.

Road and rail only: When modeOfTransportCode has a specified value, typeOfIdentification must have a specific value

Response

{
  "status": "FAILURE",
  "requestId": "${requestIdForSubmission}",
  "notificationDate": "${dateTimeResultWasReady}"
  "validationErrorList": [
    {
      "description": "transport.activeBorderTransportMeans.modeOfTransportCode is ${value}, then this field should have value ${requiredValue}",
      "pointer": {
        "messageElementPath": "transport.activeBorderTransportMeans.typeOfIdentification"
      }
    }
  ]
}

Cause

With the code specified for modeOfTransportCode, typeOfIdentification must be this specific value ("requiredValue").

Correction

Change the typeOfIdentification field to the value specified as required in the validation error ("requiredValue"). Resubmit. Use the new "requestId" received in return for the new submission and verify that the asynchronous validation for this returns the field "status" with the value "SUCCESS" when the new processing is complete.

For road transport only (road-API): Cannot find the Norwegian vehicle registration number ("identificationNumber") in the vehicle registry

Response

{
  "status": "FAILURE",
  "requestId": "${requestIdForSubmission}",
  "notificationDate": "${dateTimeResultWasReady}"
  "validationErrorList": [
    {
      "description": "Could not find identificationNumber in Norwegian Public Roads Administration’s register of motor vehicles",
      "pointer": {
        "messageElementPath": "transport.activeBorderTransportMeans.identificationNumber"
      }
    }
  ]
}

Cause

You have submitted that the vehicle is Norwegian (countryCode is "NO"), but the registration number ("identificationNumber") is not found in the Norwegian vehicle registry.

Correction

If the vehicle is Norwegian, verify that the identificationNumber is correct according to what is registered in the Norwegian vehicle registry. Resubmit. Use the new "requestId" received in return for the new submission and verify that the asynchronous validation for this returns the field "status" with the value "SUCCESS" when the new processing is complete.

Cannot find the customs declaration among the valid declarations in our system

Response

{
  "status": "FAILURE",
  "requestId": "${requestIdForSubmission}",
  "notificationDate": "${dateTimeResultWasReady}"
  "validationErrorList": [
    {
      "description": "Customs declaration is not valid",
      "pointer": {
        "messageElementPath": "consignmentHouseLevel.previousDocuments[${indexInList}]"
      }
    }
  ]
}

Cause

The declaration specified with "declarantNumber," "declarationDate," and "sequenceNumber" cannot be linked to the House Consignment. For the referenced customs declaration to be validated successfully, it must be submitted against a defined expedition unit in TVINN. Currently, this is only expedition unit 441001.

Correction

Verify that the declaration information is correctly registered. Resubmit. Use the new "requestId" received in return for the new submission and verify that the asynchronous validation for this returns the field "status" with the value "SUCCESS" when the new processing is complete.

The customs declaration specified has an invalid status in our systems

Response

{
  "status": "FAILURE",
  "requestId": "${requestIdForSubmission}",
  "notificationDate": "${dateTimeResultWasReady}"
  "validationErrorList": [
    {
      "description": "Customs declaration is in wrong state",
      "pointer": {
        "messageElementPath": "consignmentHouseLevel.previousDocuments[${indexInList}]"
      }
    }
  ]
}

Cause

The declaration specified with "declarantNumber," "declarationDate," and "sequenceNumber" was found in our systems but has an incorrect status. This usually means that the declaration has already been completed.

Correction

Ensure that the declaration has been processed and has a valid status. Resubmit. Use the new "requestId" received in return for the new submission and verify that the asynchronous validation for this returns the field "status" with the value "SUCCESS" when the new processing is complete.

The specified field cannot have a value when a specified customs procedure is provided ("importProcedure" is X)

Response

{
  "status": "FAILURE",
  "requestId": "${requestIdForSubmission}",
  "notificationDate": "${dateTimeResultWasReady}"
  "validationErrorList": [
    {
      "description": "Field cannot be filled out when consignmentHouseLevel.importProcedure is ${importProcedureType}",
      "pointer": {
        "messageElementPath": "consignmentHouseLevel.previousDocuments[${indexInList}].${fieldName}"
      }
    }
  ]
}

Cause

If you have specified that the customs procedure ("importProcedure") is a particular value, you cannot fill out this field, i.e., the field indicated in "messageElementPath." This error occurs when the specified customs procedure is different from "IMMEDIATE_RELEASE_IMPORT" while values are provided in the fields related to the reference of the customs declaration ("consignmentHouseLevel.previousDocuments.sequenceNumber," and/or "consignmentHouseLevel.previousDocuments.declarantNumber," and/or "consignmentHouseLevel.previousDocuments.declarationDate").

Correction

Either change the importProcedure or remove the value from this field. Resubmit. Use the new "requestId" received in return for the new submission and verify that the asynchronous validation for this returns the field "status" with the value "SUCCESS" when the new processing is complete.

The field cannot have a value for transit ("N820") if you have specified the procedure that the consignment was subject to until crossing the border into Norway ("outgoing procedure") as export ("EXP")

Response

{
  "status": "FAILURE",
  "requestId": "${requestIdForSubmission}",
  "notificationDate": "${dateTimeResultWasReady}"
  "validationErrorList": [
    {
      "description": "Field cannot have value N820 out when consignmentHouseLevel.outgoingProcedure is EXP",
      "pointer": {
        "messageElementPath": "consignmentHouseLevel.previousDocuments[${indexInList}].typeOfReference"
      }
    }
  ]
}

Cause

If you have specified that the procedure the consignment was subject to until crossing the border into Norway ("outgoingProcedure") is export (with value "EXP"), you cannot provide the value "N820" in this field. This applies to references to previous customs procedures that the goods have been subject to. If you specify that the previous customs procedure is export, you cannot refer to a transit reference.
See valid customs procedures: https://toll.github.io/api/mo-vei-EN.html#utfyllingForsend

Correction

Either change the value in the field or the outgoingProcedure. Resubmit. Use the new "requestId" received in return for the new submission and verify that the asynchronous validation for this returns the field "status" with the value "SUCCESS" when the new processing is complete.

When the referenced document ("typeReference") is a customs declaration ("CUDE"), the specified field is mandatory

Response

{
  "status": "FAILURE",
  "requestId": "${requestIdForSubmission}",
  "notificationDate": "${dateTimeResultWasReady}"
  "validationErrorList": [
    {
      "description": "Required field when typeReference is CUDE",
      "pointer": {
        "messageElementPath": "consignmentHouseLevel.previousDocuments[${indexInList}].${fieldRequired}"
      }
    }
  ]
}

Cause

You have specified that the referenced document is a customs declaration ("typeReference" with value "CUDE"), so you must also provide a value in the specified field (the field is specified in the error message).

Correction

Either change the typeReference or provide a value for the field. Resubmit. Use the new "requestId" received in return for the new submission and verify that the asynchronous validation for this returns the field "status" with the value "SUCCESS" when the new processing is complete.

If one or more document references ("previousDocument") have been specified, the customs procedure (field "importProcedure") must be provided

Response

{
  "status": "FAILURE",
  "requestId": "${requestIdForSubmission}",
  "notificationDate": "${dateTimeResultWasReady}"
  "validationErrorList": [
    {
      "description": "importProcedure is required when any consignmentHouseLevel.previousDocuments[] is provided",
      "pointer": {
        "messageElementPath": "consignmentHouseLevel.importProcedure"
      }
    }
  ]
}

Cause

You have submitted one or more document references (objects in the "previousDocuments" list) but did not provide a customs procedure (value in the "importProcedure" field).

Correction

Either provide a value for the importProcedure field or remove all objects from the previousDocuments list. Resubmit. Use the new "requestId" received in return for the new submission and verify that the asynchronous validation for this returns the field "status" with the value "SUCCESS" when the new processing is complete.

You can only provide one document reference to a customs declaration (an object in the "previousDocuments" list) of type customs declaration (with "typeOfReference" = "CUDE")

Response

{
  "status": "FAILURE",
  "requestId": "${requestIdForSubmission}",
  "notificationDate": "${dateTimeResultWasReady}"
  "validationErrorList": [
    {
      "description": "PreviousDocuments can only contain one document of type CUDE",
      "pointer": {
        "messageElementPath": "consignmentHouseLevel.previousDocuments"
      }
    }
  ]
}

Cause

You have submitted more than one customs declaration (object in the "previousDocuments" list) with the value "CUDE" in the "typeOfReference" field. Only one customs declaration per consignment is allowed.

Correction

Ensure that there is only one object with the "typeOfReference" value "CUDE" in the previousDocuments list. Resubmit. Use the new "requestId" received in return for the new submission and verify that the asynchronous validation for this returns the field "status" with the value "SUCCESS" when the new processing is complete.

If the document reference is something other than a customs declaration ("typeOfReference" ≠ "CUDE"), the reference must be provided in the "referenceNumber" field in the "previousDocuments" object

Response

{
  "status": "FAILURE",
  "requestId": "${requestIdForSubmission}",
  "notificationDate": "${dateTimeResultWasReady}"
  "validationErrorList": [
    {
      "description": "Field should have value unless typeOfReference is CUDE",
      "pointer": {
        "messageElementPath": "consignmentHouseLevel.previousDocuments[${indexInList}].referenceNumber"
      }
    }
  ]
}

Cause

When referring to document types other than customs declarations, the "referenceNumber" field in the "previousDocuments" object should be used to provide this reference (typically MRN or similar).
You have submitted an object in the "previousDocuments" list with a value other than "CUDE" in the "typeOfReference" field, while not providing a value in the "referenceNumber" field. It is required that this field be provided with a value unless "typeOfReference" has the value "CUDE".

Correction

Change the object to have the value "CUDE" in the typeOfReference field, or provide a valid value in the referenceNumber field. Resubmit. Use the new "requestId" received in return for the new submission and verify that the asynchronous validation for this returns the field "status" with the value "SUCCESS" when the new processing is complete.

Incomplete documentation

In certain cases, the information submitted may not be sufficient to complete processing. At the endpoint /house-consignment/validation-status/{requestIds}, you will receive a list of cause codes under "incompleteDocumentationReasonList". It is also possible to query the endpoints /house-consignment/transport-document/status or /master-consignment/transport-document/status to obtain this information.

Document Status Format

If the submission is complete, the field "documentStatus" will have the value "SUCCESS"; otherwise, it will have "INCOMPLETE". If the status is "INCOMPLETE", an "incompleteDocumentationReasonList" will be provided, listing cause codes explaining why the submission was deemed incomplete. Examples of values that can appear as cause codes can be found here: https://toll.github.io/api/mo-kodeverk-EN.html#incompleteDocumentationReason

{
  "documentNumber": "${documentNumber}",
  "type": "${documentType}",
  "documentStatus": "${documentProccessingStatus}",
  "incompleteDocumentationReasonList": [
    "${reasonsIfStatusIsIncomplete}"
  ]
}

Document status INCOMPLETE

Response

{
  "documentNumber": "${documentNumber}",
  "type": "${documentType}",
  "documentStatus": "INCOMPLETE",
  "incompleteDocumentationReasonList": [
    "${reasonsIfStatusIsIncomplete}"
  ]
}

Cause

You have a submission that does not meet the requirements for a complete submission for the selected customs procedure. See: https://toll.github.io/api/mo-vei-EN.html#utfyllingForsend

Correction

Modify the submission to meet the requirements for the selected customs procedure. See: https://toll.github.io/api/mo-vei-EN.html#utfyllingForsend. Submit the updated submission with the changes (HTTP PUT). Verify that "/transport-document/status" eventually returns with status "SUCCESS" after reprocessing.