Error Handling
The Automation REST API returns a common set of errors. This section describes the type of error messages that are returned by the API and the format of the messages.
Error Response format
The format of the body of all error responses from the API is:
{
"code" : "APPLICATION_ERROR_CODE",
"message" : "Error X occurred.",
"errors" : [
{
"code" : "APPLICATION_SUB_ERROR_CODE",
"message" : "Sub-error Y occurred.",
"field" : "Name"
}
]
}The meaning of the fields used in this format are described in the table:
Field | Description |
|---|---|
| An application error code. This can be used to uniquely identify the error. |
| A short message to describe the error. This will offer more context on the error. For example, the id of an entity that could not be found. |
| A list of one or more sub-errors that describe the issue in more detail. One example of this is when validation fails when creating a resource. In that situation, for each missing field a different sub-error will be present in the response. It is not always present. |
| An application sub-error code. |
| A short message to describe the sub-error. |
| If applicable, the name of a field that isn't valid. For example, when a required field is not specified when creating a resource. If an error occurs in a top-level field, it is the name of the field that is returned in the error message. If the error occurs in a nested entity, the error message will return the full path to the erroneous field. For example, |
API Errors
There are many errors that can be generated by the API. The table below provides a representative sample of the errors that may be encountered, together with an explanation as to the likely cause of the error.
HTTP Status code | Application Error code | Description |
|---|---|---|
400 BAD_REQUEST | BAD_REQUEST | An error occurred due to invalid user input. If the input can be classified as being syntactically or semantically invalid, then the However, If the input cannot be classified as |
400 BAD_REQUEST | INVALID_INPUT | One of more of the properties that were supplied to create or modify an object are not syntactically or semantically valid. |
400 BAD_REQUEST | DEPENDENCY_NOT_FOUND | One of the resources that the resource currently being created or updated relies on could not be found. |
400 BAD_REQUEST | PRECONDITION_FAILED | The operation cannot be completed due to the current state of the system. |
401 UNAUTHORIZED | UNAUTHORIZED | The client is not authenticated. |
403 FORBIDDEN | FORBIDDEN | The current user does not have permissions for the operation being attempted. |
403 FORBIDDEN | INVALID_LICENCE_KEY | There is a problem with the licence key. It might be invalid, expired or missing. Please contact your account manager for help. |
403 FORBIDDEN | FEATURE_DISABLED | A required feature for this operation is disabled. Please contact your system administrator for help. |
403 FORBIDDEN | EXTERNAL_USER_MANAGEMENT | The users of the system are managed externally and cannot be accessed by this operation. |
404 NOT_FOUND | NOT_FOUND | The requested resource does not exist in the system. |
409 CONFLICT | CONFLICT | The resources affected by the operation have been modified concurrently. |
500 INTERNAL_SERVER_ERROR | CONFIG_MISMATCH | There is an issue with the configuration of the environment. |
500 INTERNAL_SERVER_ERROR | INTERNAL_SERVER_ERROR | An unexpected error occurred. |
501 NOT_IMPLEMENTED | This endpoint is not implemented. | |
503 SERVICE_UNAVAILABLE | SERVICE_UNAVAILABLE | External components such as Privitar On Demand or SecureLink could not be reached. |
API Sub-errors
The API returns the following Sub-errors. All these errors are flagged as 400 BAD_REQUEST response status codes.
Application Error Code | Application Sub-Error Code | Description |
|---|---|---|
INVALID_INPUT | MISSING_FIELD | No value was specified for a mandatory field. |
INVALID_INPUT | EMPTY_FIELD | The supplied value is empty or only contains whitespace. |
INVALID_INPUT | MAX_LENGTH_FIELD | The supplied value exceeds the maximum supported length. |
INVALID_INPUT | OUT_OF_BOUNDS_LIST | The specified collection of values exceeds the maximum supported amount. |
INVALID_INPUT | INVALID_FIELD | The specified value is not valid for the respective field. |
INVALID_INPUT | INVALID_OBJECT | One of the objects that were specified for the current operation is not valid. |
BAD_REQUEST | INVALID_QUERY_PARAM | One of the query parameters is not valid. |
INVALID_INPUT | INVALID_FIELD_URI | A field was expecting a valid URI but the one sent was malformed. |
INVALID_INPUT | INVALID_FIELD_STRING_FORMAT | A field was expecting to conform to some pattern, but it did not. |
INVALID_INPUT | INVALID_FIELD_DATE_FORMAT | A field was expecting a valid date string format (according to |
INVALID_INPUT | INVALID_TIME_FORMAT | A field was expecting a valid time string format (according to |
INVALID_INPUT | INVALID_FIELD_NUMERIC_BOUNDS | A field was expecting a number between either a minimum bound, maximum bound or both; and it violated these bounds. |