Error messages – Planning
Validation Errors
The following error messages may be returned due to omitted or incorrectly entered parameters. The error code returned by the API will be 400 (Bad Request), and the returned JSON will have the following structure:
{
"logId": "5e8f64f0-0ece-4e26-84c3-7ff889eff092",
"message": "Validation failed",
"errors": [
"sites may not be empty",
"operations[0].customerSite reference not found",
"operations[1].customerSite reference not found"
]
}
The table below shows the validations applied to each entity and the error message returned:
| Parameter | Validations | Error Messages |
| sites | notEmpty | may not be empty |
| depots | notEmpty | may not be empty |
| operations | notEmpty | may not be empty |
| vehicleTypes | notEmpty | may not be empty |
| vehicles | notEmpty | may not be empty |
| products | notEmpty | may not be empty |
| legislationProfiles | notEmpty | may not be empty |
| logisticConstraints | notEmpty | may not be empty |
| optimizationProfile | notBlank | is mandatory |
| optimizationProfile | invalid profile | optimizationProfile {name} not found |
| tripsProfile | notBlank | is mandatory |
| startDate | notNull | is mandatory |
The tables below show the validations applied for each specific entity:
| operations | ||
| Parameter | Validations | Error Messages |
| id | notBlank, unique | is mandatory, already exists |
| weight | notNull, notNegative | is mandatory, may not be negative |
| volume | notNull, notNegative | is mandatory, may not be negative |
| product | notBlank, validReference | is mandatory, reference not found |
| type | notBlank, isContainedIn | is mandatory, does not have a valid value. Allowed values: [COLLECTION, DELIVERY] |
| priority | notNegative | may not be negative |
| depotSite | notBlank, validReference | is mandatory, reference not found |
| customerSite | notBlank, validReference | is mandatory, reference not found |
| customerTimeWindows | notEmpty | may not be empty |
| vehicles | ||
| Parameter | Validations | Error Messages |
| name | notBlank, unique | is mandatory, already exists |
| vehicleType | notBlank, validReference | is mandatory, reference not found |
| legislationProfile | notBlank, validReference | is mandatory, reference not found |
| availablePeriods | notEmpty | may not be empty |
| priority | notNegative | may not be negative |
| vehicleTypes | ||
| Parameter | Validations | Error Messages |
| name | notNull, unique | is mandatory, already exists |
| maxWeight | notNull, notNegative | is mandatory, may not be negative |
| maxVolume | notNull, notNegative | is mandatory, may not be negative |
| size | notNegative | may not be negative |
| maxSitesNumber | notNegative | may not be negative |
| compartmentsAccessMode | notNull, isContainedIn | is mandatory, does not have a valid value. Allowed values: [ALL_COMPARTMENTS, REAR_ACCESS] |
| trip.calculationMode | notNull | is mandatory |
| trip.toll.vehicleType | notNull | is mandatory |
| sites and depots | ||
| Parameter | Validations | Error Messages |
| name | notBlank, unique | is mandatory, already exists |
| coordinates | notNull | is mandatory |
| coordinates.latitude | notNull, range(-90, 90) | is mandatory, must be between -90 and 90 |
| coordinates.longitude | notNull, range(-180, 180) | is mandatory, must be between -180 and 180 |
| logisticConstraints | notBlank, validReference | is mandatory, reference not found |
| legislationProfile | ||
| Parameter | Validations | Error Messages |
| name | notBlank, unique | is mandatory, already exists |
| maxContinuousDrivingTime | greaterThanZero | must be greater than zero |
| drivingPauseDuration | greaterThanZero | must be greater than zero |
| maxContinuousWorkingTime | greaterThanZero | must be greater than zero |
| workingPauseDuration | greaterThanZero | must be greater than zero |
| callback | ||
| Parameter | Validations | Error Messages |
| url | notNull | is mandatory |
| url | Invalid url | does not have a valid value. Example of allowed values: http://www.foo.br, https://www.foo.br, http://www.foo.br/bar |
The validations below apply to the time windows described in the parameters vehicles[n].availablePeriods, operations[n].customerTimeWindows and operations[n].depotTimeWindows:
| timeWindow | ||
| Parameter | Validations | Error Messages |
| start | notNull | is mandatory |
| end | notNull | is mandatory |
| start, end | start < end | must have the start less than to the end |
| start, end | start != end | must not start the same as the end |
| end | end < startDate | must have at least one timeWindow with end after problem’s startDate |
Processing errors
The following error messages may be returned when querying the request processing status through the endpoints https://api.maplink.global/planning/v1/events?jobId={{planningId}} and https://api.maplink.global/planning/v1/jobs/{{planningId}}.
The error message follows the following structure:
{
"id": "688d267a74be5d22a1ac9002",
"jobId": "688d26787766ef668397ff50",
"type": "ERROR",
"description": "{'logId':'db496388-c45a-4902-af42-0971578cbb38','errors':[{'code':'TECHNICAL_ERROR','description':'global.maplink.matrixinprocessor.exception.ProcessException: [ProcessError(code=INVALID_SITE_POSITION, description=Some sites have not been positionned, detail=[Cliente1])]'}]}",
"createdAt": 1754080890262
}
The event returns with the type equal to ERROR and the following messages can be returned in description:
| Error Message | Cause |
| {‘logId’:’{{logId}}‘,’errors’: [{‘code’:’TECHNICAL_ERROR’,’description’:’Not possible to create route between sites {{siteId}} and {{siteId}}‘}]} | No path could be found between the two points. The point may be misplaced or there may be no path at all, such as a point on a dead-end, one-way street. |
| Error in process MRS: Cannot find point {{latitude}},{{longitude}} | The location of the provided coordinates could not be found. It could be that some coordinates are invalid, falling into the ocean, for example. |
Example of a route with an error message:
[
{
"id": "688d29735e59ee6e88b67adb",
"jobId": "688d29737766ef668397ff52",
"type": "STATUS_CHANGE",
"description": "ENQUEUED",
"createdAt": 1754081651310
},
{
"id": "688d297374be5d22a1ac900b",
"jobId": "688d29737766ef668397ff52",
"type": "STATUS_CHANGE",
"description": "CONVERT_TO_MATRIX",
"createdAt": 1754081651314
},
{
"id": "688d29735e59ee6e88b67adc",
"jobId": "688d29737766ef668397ff52",
"type": "PERCENT_CHANGE",
"description": "1",
"createdAt": 1754081651317
},
{
"id": "688d297308fc0e441d9e9d23",
"jobId": "688d29737766ef668397ff52",
"type": "STATUS_CHANGE",
"description": "PROCESSING",
"createdAt": 1754081651339
},
{
"id": "688d29745e59ee6e88b67add",
"jobId": "688d29737766ef668397ff52",
"type": "ERROR",
"description": "{'logId':'e687f91b-e4ce-4cbf-b6c5-8e304e281617','errors':[{'code':'TECHNICAL_ERROR','description':Not possible to create route between sites OP-1 and OP-2'}]},
"createdAt": 1754081652037
}
]
