exceptions

All PTV xServer services can throw an XServerFault which is specified in this namespace. This exception contains a message and for further details a subtype of XServerFault. There are five main subtypees of XServerFault:

See request and response for details on when a result limitation will be returned instead of an exception.

Types

This entity wraps a former exception in order to return it in a regular response, for example of a bulk or list method. This 'exception' cannot be caught but the contents can be treated as if they originate from an XServerException.

Field Name Type Required Default Since Description
message String yes - 2.5 The message of the suppressed exception.
faultInfo XServerFault yes - 2.5 The fault information of the suppressed exception.
Fault

AccessDeniedFault

extends RejectedRequestFault
since 2.11

This fault is thrown if the sender does not have the rights to execute the request. This may be due to required admin privileges or blocked methods by a middleware.

If this fault is thrown, REST and JSON calls return a http status code 403, a SOAP call returns a http status code 500.

No fields defined.
Fault

AmbiguousInsertionPositionFault

extends TripStructureFault
since 2.11

This fault is thrown if the insertion position of an order is not clearly determinable.

The insertion position of an order contained in a MoveOrdersAction can be ambiguous. Either orders from different sites shall be moved to a specified insertion position which means the resulting stop sequence is unclear. Or all orders of the target trip shall be moved such that the target trip would be dissolved after removing the orders. In that case it is not clear how to interpret the specified insertion position when there are no more stops left.

Furthermore the insertion position of a transport order contained in a stop of a MoveStopsAction can be ambiguous. More precisely a partner task belonging to a task contained in a stop of a MoveStopsAction could have multiple options where to be inserted in the target trip. For further explanation please have a look at the documentation of the MoveStopsAction.

If this fault is thrown, REST and JSON calls return a http status code 400, a SOAP call returns a http status code 500.

Field Name Type Since Description
orderId String 2.11 ID of the order with unclear insertion position.
taskType TaskType 2.11 Task type of the task with unclear insertion position.
Fault

ConfigurationFault

extends SetupFault
since 2.0

This fault is thrown if an entry in a configuration file leads to a problem.

If this fault is thrown, REST and JSON calls return a http status code 500, a SOAP call returns a http status code 500.

Field Name Type Since Description
fileName FileName (String) 2.0 The name of the configuration file that contains the wrongly configured parameter.
parameter String 2.0 The name of the wrongly configured parameter.
value String 2.0 The wrongly configured value.
Fault

DataNotAvailableFault

extends InvalidRequestFault
since 2.0

This fault is thrown if due to a specific parameter of the request certain data is required to calculate the response but the data is not available.

If this fault is thrown, REST and JSON calls return a http status code 400, a SOAP call returns a http status code 500.

Field Name Type Since Description
parameter String 2.0 The request parameter as XPath expression which requires data that is not available.
value String 2.0 The parameter's value or for comma-separated lists the part of the parameter's value that requires the data that is not available. For example, a Feature Layer theme or a missing rule or action in the corresponding Feature Layer theme.
Fault

DeliveryBeforePickupFault

extends TripStructureFault
since 2.11

This fault is thrown if a delivery task is executed before the corresponding pickup task in an input tour or a ChangeToursRequest would lead to this wrong order of tasks.

If this fault is thrown, REST and JSON calls return a http status code 400, a SOAP call returns a http status code 500.

Field Name Type Since Description
orderId String 2.11 ID of the order whose delivery task is or should be executed before the pickup task.
Fault

DepotVisitFault

extends TourStructureFault
since 2.11

This fault is thrown if a visit order is to be executed at a depot.

If this fault is thrown, REST and JSON calls return a http status code 400, a SOAP call returns a http status code 500.

Field Name Type Since Description
orderId String 2.11 ID of the visit order causing the exception.
siteId String 2.11 ID of the depot site the visit order refers to.
Fault

DistanceMatrixIdNotFoundFault

extends InvalidRequestFault
since 2.1

This fault is thrown if a distance matrix with the specified ID could not be found on the server.

If this fault is thrown, REST and JSON calls return a http status code 400, a SOAP call returns a http status code 500.

Field Name Type Since Description
distanceMatrixId String 2.1 The distance matrix ID that could not be found.
Fault

DuplicateProfileFault

extends SetupFault
since 2.6

This fault is thrown if the profile folder contains two files with the same name in different subfolders.

If this fault is thrown, REST and JSON calls return a http status code 500, a SOAP call returns a http status code 500.

Field Name Type Since Description
fileName FileName (String) 2.6 The name of the profile file that is present in two folders.
Fault

EncodedContentMapMismatchFault

extends InvalidValueFault
since 2.31

This fault is thrown if a parameter of type EncodedContent contains a value which does not match the map.

If this fault is thrown, REST and JSON calls return a http status code 400, a SOAP call returns a http status code 500.

Field Name Type Since Description
mapVersion String 2.31 The map version the encoded content should be based on.
Fault

InternalErrorFault

extends XServerFault
since 2.0

This fault is thrown if an unexpected internal error occurs. It may happen when a module runs out of memory or lacks an important resource. If the error persists, report it to PTV's xServer support.

If this fault is thrown, REST and JSON calls return a http status code 500, a SOAP call returns a http status code 500.

No fields defined.
Fault

InvalidFetchTypeFault

extends InvalidRequestFault
since 2.0

This fault is thrown if the type of a fetch request, to get the response of an asynchronous job, is invalid. For example if the response of a startPlanTours request is fetched with fetchDistanceMatrixResponse.

If this fault is thrown, REST and JSON calls return a http status code 400, a SOAP call returns a http status code 500.

Field Name Type Since Description
jobId String 2.0 ID of the asynchronous job.
Fault

InvalidLoadingSequenceFault

extends TripStructureFault
since 2.11

This fault is thrown if a site in an input tour is left although there is still load for it on the vehicle or is served although there is still load from it on the vehicle or a ChangeToursRequest would lead to this wrong loading sequence. For more information please have a look at the section valid loading sequence of the technical concept for tours and trips.

If this fault is thrown, REST and JSON calls return a http status code 400, a SOAP call returns a http status code 500.

Field Name Type Since Description
siteId String 2.11 ID of the site that violates the loading sequence structure.
Fault

InvalidProfileNameFault

extends InvalidRequestFault
since 2.0

This fault is thrown if an invalid profile name is passed

If this fault is thrown, REST and JSON calls return a http status code 400, a SOAP call returns a http status code 500.

Field Name Type Since Description
profile String 2.0 The profile name.

This fault is thrown if a request is invalid, for instance if it does not fit the WSDL specification.

If this fault is thrown, REST and JSON calls return a http status code 400, a SOAP call returns a http status code 500.

No fields defined.
Fault

InvalidTaskSequenceFault

extends StopStructureFault
since 2.11

This fault is thrown if a delivery task is not at the beginning of a stop or a pickup task is not at the end of a stop.

If this fault is thrown, REST and JSON calls return a http status code 400, a SOAP call returns a http status code 500.

Field Name Type Since Description
orderId String 2.11 ID of the transport order causing the exception.
taskType TaskType 2.11 Task type of the task causing the exception.
taskIndex Index (int) 2.11 Index of the task in tasks causing the wrong order sequence structure.
Fault

InvalidTourRequestFault

extends InvalidRequestFault
extended by OrderAlreadyPlannedFault, TourStructureFault
since 2.11

This fault is thrown if a PlanToursRequest or a ChangeToursRequest is invalid.

If this fault is thrown, REST and JSON calls return a http status code 400, a SOAP call returns a http status code 500.

No fields defined.
Fault

InvalidValueFault

extends InvalidRequestFault
extended by EncodedContentMapMismatchFault
since 2.0

This fault is thrown if a request parameter is set to an invalid value.

If this fault is thrown, REST and JSON calls return a http status code 400, a SOAP call returns a http status code 500.

Field Name Type Since Description
parameter String 2.0 An xPath like specification of the parameter that is set to an invalid value.
value String 2.0 The invalid value.
Fault

LicenseFault

extends SetupFault
since 2.0

This fault is thrown if a license is missing for some services or if some data content is unlicensed.

If this fault is thrown, REST and JSON calls return a http status code 500, a SOAP call returns a http status code 500.

Field Name Type Since Description
unlicensedServices String[] 2.0 A list of services that are unlicensed.
Fault

LicenseViolationFault

extends InvalidRequestFault
since 2.0

This fault is thrown if a request exceeds the licensed range of a specific feature. For example if only data in Germany is licensed, but coordinates in Switzerland are requested.

If this fault is thrown, REST and JSON calls return a http status code 400, a SOAP call returns a http status code 500.

Field Name Type Since Description
key String 2.0 The name of the license key that is violated.
Fault

MissingParameterFault

extends InvalidRequestFault
since 2.0

This fault is thrown if a required parameter is missing in the request.

If this fault is thrown, REST and JSON calls return a http status code 400, a SOAP call returns a http status code 500.

Field Name Type Since Description
parameter String 2.0 The xPath to the missing parameter.
Fault

OrderAlreadyPlannedFault

extends InvalidTourRequestFault
since 2.11

This fault is thrown if a AddTripAction or InsertionPositionsForOrdersQuery contains an order that is not an unplanned order.

If this fault is thrown, REST and JSON calls return a http status code 400, a SOAP call returns a http status code 500.

Field Name Type Since Description
orderId String 2.11 ID of the order in the AddTripAction or InsertionPositionsForOrdersQuery that is already planned.
Fault

ParameterConflictFault

extends InvalidRequestFault
since 2.0

This fault is thrown if two parameters are in conflict with each other.

If this fault is thrown, REST and JSON calls return a http status code 400, a SOAP call returns a http status code 500.

Field Name Type Since Description
parameterA String 2.0 The xPath to the first conflicting parameter.
parameterB String 2.0 The xPath to the second conflicting parameter.
valueA String 2.0 The value of the first conflicting parameter.
valueB String 2.0 The value of the second conflicting parameter.
Fault

ProcessingFault

extends XServerFault
extended by ProcessingTimedOutFault, RouteNotFoundFault, WaypointNotLinkableFault
since 2.0

This fault is thrown if the request could not be processed by the service.

If this fault is thrown, REST and JSON calls return a http status code 500, a SOAP call returns a http status code 500.

No fields defined.
Fault

ProcessingTimedOutFault

extends ProcessingFault
since 2.16

This fault is thrown if the processing of a request is aborted by an internal timeout. In contrast to RequestTimedOutFault, there is no user-configurable timeout value that could be changed to prevent this. An internal timeout is meant to control corner cases where an algorithm behaves poorly.

If this fault is thrown, REST and JSON calls return a http status code 500, a SOAP call returns a http status code 500.

No fields defined.
Fault

QueueOverflowFault

extends RejectedRequestFault
since 2.0

This fault is thrown if there are too many requests in the xServer's request queue. If this happens frequently, you may have to increase the size of the request queue in the xServer configuration.

If this fault is thrown, REST and JSON calls return a http status code 503, a SOAP call returns a http status code 500.

No fields defined.

This fault is thrown if the request is rejected by the server for some reason.

If this fault is thrown, REST and JSON calls return a http status code 500, a SOAP call returns a http status code 500.

No fields defined.
Fault

RequestDeletedFault

extends RejectedRequestFault
since 2.0

This fault is thrown if the request was deleted from the outside, for example via the status monitor.

If this fault is thrown, REST and JSON calls return a http status code 400, a SOAP call returns a http status code 500.

No fields defined.
Fault

RequestTimedOutFault

extends RejectedRequestFault
since 2.0

This fault is thrown if the request ran into a timeout. If this happens frequently, you may have to increase the timeout values in the xServer configuration.

If this fault is thrown, REST and JSON calls return a http status code 500, a SOAP call returns a http status code 500.

No fields defined.
Fault

RouteNotFoundFault

extends ProcessingFault
since 2.0

This fault is thrown if a route between the given waypoints could not be found with the current configuration and profile. This may be caused by road blockings without the possibility of a detour.

If this fault is thrown, REST and JSON calls return a http status code 400, a SOAP call returns a http status code 500.

Field Name Type Since Description
waypointIndex Index (Integer) 2.32 The index of the input waypoint where the problematic part that could not be routed starts, i.e., the problematic part of the route is between this input waypoint and the next one. Note that only the first problematic part that was encountered during the routing algorithm is reported.
Fault

ServiceNotConfiguredFault

extends RejectedRequestFault
since 2.0

This fault is thrown if a requested service is not configured in the current deployment.

If this fault is thrown, REST and JSON calls return a http status code 500, a SOAP call returns a http status code 500.

Field Name Type Since Description
service String 2.0 The name of the service that is not configured.
Fault

SetupFault

extends XServerFault
extended by ConfigurationFault, DuplicateProfileFault, LicenseFault
since 2.0

This fault is thrown if an error occurred during the setup of the xServer. SetupFaults are never raised by a request, they only occur on startup.

If this fault is thrown, REST and JSON calls return a http status code 500, a SOAP call returns a http status code 500.

No fields defined.
Fault

SingleDepotPerTourRestrictionFault

extends TourStructureFault
since 2.11

This fault is thrown if the singleDepotPerTour restriction is set but an input tour consists of multiple depots or a ChangeToursRequest would lead to multiple depots per tour.

If this fault is thrown, REST and JSON calls return a http status code 400, a SOAP call returns a http status code 500.

Field Name Type Since Description
vehicleId String 2.11 ID of the vehicle serving the input tour with invalid structure in case of a PlanToursRequest. In case of a ChangeToursRequest this parameter contains the ID of the vehicle that would serve a tour with invalid structure.
Fault

SingleTripPerTourRestrictionFault

extends TourStructureFault
since 2.11

This fault is thrown if the singleTripPerTour restriction is set but an input tour consists of multiple trips or a ChangeToursRequest would lead to multiple trips per tour.

If this fault is thrown, REST and JSON calls return a http status code 400, a SOAP call returns a http status code 500.

Field Name Type Since Description
vehicleId String 2.11 ID of the vehicle serving the input tour with invalid structure in case of a PlanToursRequest. In case of a ChangeToursRequest this parameter contains the ID of the vehicle that would serve a tour with invalid structure.
Fault

StopStructureFault

extends TripStructureFault
extended by InvalidTaskSequenceFault
since 2.11

This fault is thrown if a stop structure is violated. For more information please have a look at the technical concept Orders, Locations, and Stops.

If this fault is thrown, REST and JSON calls return a http status code 400, a SOAP call returns a http status code 500.

Field Name Type Since Description
stopIndex Index (int) 2.11 Index of the stop in stops of the trip containing the wrong structure.

This fault is thrown if a tour structure is violated. For more information please have a look at the section valid tour structures of the technical concept for tours and trips.

If this fault is thrown, REST and JSON calls return a http status code 400, a SOAP call returns a http status code 500.

No fields defined.
Fault

TransformFault

extends InvalidRequestFault
since 2.0

This fault is thrown if an exception occured during transformation of input coordinates, geometries or bounds.

If this fault is thrown, REST and JSON calls return a http status code 400, a SOAP call returns a http status code 500.

Field Name Type Since Description
wrongCoordinate Coordinate 2.0 Represents the coordinate which could not be transformed.
srid String 2.0 The SRID of the request coordinates.
Fault

TripDepotStructureFault

extends TripStructureFault
since 2.11

This fault is thrown if a trip structure is violated regarding depot sites.

This fault references one of the following:

  • A pickup task at a depot that is not part of the consecutive pickup depot stops at the start of a trip.
  • A task that is not a delivery at a depot but is executed after or in between the consecutive delivery depot stops at the end of a trip.

For more information please have a look at the technical concepts Tours and Trips and Orders, Locations and Stops.

If this fault is thrown, REST and JSON calls return a http status code 400, a SOAP call returns a http status code 500.

Field Name Type Since Description
orderId String 2.11 ID of the order that violates the trip depot structure.
taskType TaskType 2.11 Task type of the task that violates the trip depot structure.

This fault is thrown if a trip structure is violated. For more information please have a look at the section valid tour structures of the technical concept for tours and trips.

If this fault is thrown, REST and JSON calls return a http status code 400, a SOAP call returns a http status code 500.

Field Name Type Since Description
vehicleId String 2.11 ID of the vehicle serving the input tour with invalid structure in case of a PlanToursRequest. In case of a ChangeToursRequest this parameter contains the ID of the vehicle that would serve a tour with invalid structure.
tripId String 2.11 ID of the input trip with invalid structure in case of a PlanToursRequest. In case of a ChangeToursRequest this parameter contains the ID of the trip that would have an invalid structure.
Fault

TripsMergedFault

extends TourStructureFault
since 2.11

This fault is thrown if a ChangeToursRequest results in merging two trips.

If this fault is thrown, REST and JSON calls return a http status code 400, a SOAP call returns a http status code 500.

Field Name Type Since Description
vehicleId String 2.11 ID of the vehicle that would serve a tour with invalid structure.
tripIdA String 2.11 ID of the trip that would be merged with the trip corresponding to tripIdB.
tripIdB String 2.11 ID of the trip that would be merged with the trip corresponding to tripIdA.
objectId String 2.11 ID of the object in the ChangeToursAction that would cause the merge of two trips.
Fault

UTCOffsetNotDeterminableFault

extends InvalidRequestFault
since 2.14

This fault is thrown if the UTC offset for a request depending on some reference time could not be determined.

If this fault is thrown, REST and JSON calls return a http status code 400, a SOAP call returns a http status code 500.

No fields defined.
Fault

WaypointNotLinkableFault

extends ProcessingFault
since 2.0

This fault is thrown if some routing waypoints could not be linked to the road network.

If this fault is thrown, REST and JSON calls return a http status code 400, a SOAP call returns a http status code 500.

Field Name Type Since Description
waypointIndices Index[] (Integer[]) 2.0 The list of indices of waypoints that could not be linked. The indices refer to the array of waypoints in the request.
locationsIndices Index[] (Integer[]) 2.33 The list of indices of locations that could not be linked. The indices refer to the array of locations in the request.

The base type for all types of fault info that can be included in an XServerException.

If this fault is thrown, REST and JSON calls return a http status code 500, a SOAP call returns a http status code 500.

Field Name Type Since Description
hint String 2.0 A free-text hint what to do to fix the problem.
Exception

XServerException

This is the exception which is thrown by all xServer operations. See the included XServerFault and its subtypes for details.

The http status code that is returned when an exception is thrown depends on the type of XServerFault that is included in the exception.

Field Name Type Description
message String The detailed message.
faultInfo XServerFault Contains detailed information on this exception.

Diagrams

XServer Exception Hierarchy

Setup Faults

Rejected Request Faults

General Invalid Request Faults

Module-Specific Invalid Request Faults

Processing Faults

Invalid Tour Request Faults