Error Handling
General
Every AOP function call can return the following error object instead of its specified result:
Error
| Property | Type | Description |
|---|---|---|
| Id | string | A per function unique ID to identify and handle the error. |
| Message | string | An error description in human-readable form and english language. |
| Data | value{} | Depending on the error, additional properties can be provided here for further information. |
The error Id is a Symbol Path. Various errors can be grouped together to allow a collective handling. Given the error ids group.error1, group.error2, group.error3 for example, they all could be handled by matching for group.
The Message is intended to be used by the developer to quickly grasp the issue at hand. It is also possible to display this message directly to the user; however, to improve the user experience, translated messages should be used. See Localization.
All possible properties of the Data field are listed below in the description of the various errors.
For additional protocol level details, please check the Function calls documentation.
Global errors
Certain errors can occur on every function call and thus are documented globally and not on a per-function basis. They usually indicate an error on the developer’s side and seldom can be fixed by the users themselves.
Call.Malformed
The call could not process the request due to malformed packet or frame data.
Call.Method.NotLicensed
The call could not be processed because the license does not allow it. This has priority over Call.Method.NotAvailable.
Additional properties:
| Property | Type | Description |
|---|---|---|
| Method | string | The requested function or notification name. |
Call.Method.NotAvailable
The requested function or notification does not or cannot exist.
Additional properties:
| Property | Type | Description |
|---|---|---|
| Method | string | The requested function or notification name. |
| Client | string | (Optional) The requested client, if specified in the call. |
Call.Method.NotAllowed ≥aop 0.3.0
The requested function or notification isn’t allowed in the current context.
Call.Param.Missing
A required parameter is missing.
Additional properties:
| Property | Type | Description |
|---|---|---|
| Param | string | Name of the missing parameter. |
Call.Param.Type
A parameter has the wrong type and can’t be converted to the correct type, e.g. ‘abc’ was provided for a int type.
Additional properties:
| Property | Type | Description |
|---|---|---|
| Param | string | Name of the incorrect typed parameter. |
Call.Param.Value
A parameter has the wrong value, e.g. it is out of the valid range or in case of enums does not map to value within that enum.
Additional properties:
| Property | Type | Description |
|---|---|---|
| Param | string | Name of the incorrect parameter. |
Call.Failure
An unspecified error (e.g., an unhandled exception) has occured while executing the called function.
Common errors
Various functions throughout the AOP API share certain errors, e.g., data related errors.
Developers are encouraged to use common errors if they match the issue before defining their own.
Data.Forbidden
The caller does not have the required permissions to access the data.
Additional properties:
| Property | Type | Description |
|---|---|---|
| Type | string | Data type, e.g. ‘Datapoint’ |
| Id | string | ID of the requested data, the meaning of this field depends on the ’type’ property. |
Data.NotFound
The requested data was not found or the caller does not have the required permission to access it.
Additional properties:
| Property | Type | Description |
|---|---|---|
| Type | string | Data type, e.g. ‘Datapoint’ |
| Id | string | ID of the requested data, the meaning of this field depends on the ’type’ property. |
Data.Validation
One or more Properties within the submitted Data Object were invalid.
Additional properties:
| Property | Type | Description |
|---|---|---|
| Type | string | Data type, e.g. ‘Datapoint’ |
| Id | string | ID of the requested data, the meaning of this field depends on the ’type’ property. |
| ValidationResult | ErrorDataValidationResult[] | List of Properties that failed validation. |
Operation.NotAvailable
The Operation is unavailable. This can be temporary or permanent.
Additional properties:
| Property | Type | Description |
|---|---|---|
| Cmd | string | ID of the Operation in question. |
Operation.Param.Type
A parameter has the wrong type and can’t be converted to the correct type, e.g. ‘abc’ was provided for a int type.
Additional properties:
| Property | Type | Description |
|---|---|---|
| Param | string | Name of the incorrect typed parameter. |
Operation.Param.Value
A parameter has the wrong value, e.g. it is out of the valid range or in case of enums does not map to value within that enum.
Additional properties:
| Property | Type | Description |
|---|---|---|
| Param | string | Name of the incorrect parameter. |
Operation.Canceled
The Operation was canceled. Details can be found in the error message.
Precondition.Failed
Specific required conditions were not satisfied before processing. Details can be found in the error message.
Used objects
ErrorDataValidationResult
| Property | Type | Description |
|---|---|---|
| Property | string | The erroneous Property’s path. |
| Type | string | See EnumErrorConsistencyErrorType. |
| Message | string | (Optional) A textual representation of the error in english language that gives an extended explanation of the problem. |
EnumErrorConsistencyErrorType
| Name | Value | Description |
|---|---|---|
| Range | range | Value is in incorrect range. |
| Hierarchy | hierarchy | Value breaks hierarchy, e.g. incorrect parent ID. |
| CycleDetect | cycledetect | Value leads to a cycle between data objects. |
Localization
How errors are handled is usually application-specific, as factors like available screen space, user knowledge level and UI design have to be considered.
For Global and Common errors a translated title and description text can be retrieved by using the following schema as a LNG id:
error.api.<id> for a short error title, e.g. error.api.Call.Malformed and
error.api.<id>@desc for a longer description, e.g. error.api.Call.Malformed@desc.
Individual errors might also support this feature, please check the corresponding function documentation to see if a specific error is providing translated strings or not.