This page explains the idea behind common error codes and presents a list of standardized common error codes incl. parameters.
Introduction
Not all requests against CTMS APIs will be processed successfully. Because CTMS is a REST API, it primarily signals error conditions via HTTP status codes. A problem with bare HTTP status code is their very general nature, e.g. what does "400 - Bad Request" actually mean? Usually, code handling an error condition must do some analysis of the error’s context, which often means to consider the sent request and parse the response of the error, if any.
Example:
if (response.getHttpStatus() == 400) {
// Now, what? Need more checks to understand the error condition.
}
The CTMS Approach
However, CTMS does still use HTTP status codes to signal error conditions primarily, but it defines some standards regarding the content of the response. CTMS uses a system of structured error codes, which associates a symbolic error code to an HTTP status and a set of optional parameters. Esp. the combination of symbolic error codes to parameters allow the receiver of the error to precisely determine the error condition.
Example of a body with structured error information:
{
"code": "avid.mam.assets.access/CTMS/INVALID_PARAMETER",
"params": {
"message": "Not a valid mob id (UMID): abraxas",
"parameterName": "mobID"
},
"message": "Not a valid mob id (UMID): abraxas",
"status": 400
}
The Code
The leading piece of information in the structured error is the "code" property which contains the symbolic code, such as "avid.mam.assets.access/CTMS/INVALID_PARAMETER". As can be seen the code as such has some segments separated by /.
The first segment, avid.mam.assets.access, corresponds to the service type of the service that issued the error. The platform automatically prepends the service type to the symbolic error code this way. Also structured errors issued from genuine platform services, carry their service type preprended to the code, e.g. "avid.upstream/UNAUTHENTICATED". - To check a specific error code that can be valid for multiple services, this first segment should be excluded from the evaluation/analysis/comparison.
The second segment CTMS designates a structured error code as "standard CTMS error code", which has a defined meaning in the CTMS context.
The third segment, INVALID_PARAMETER in this case, makes up the specific sort of error.
The known standard CTMS error codes are listed below.
The Parameters
A structured error can carry parameters, more correctly parameter-argument-pairs in the "params" property, which can yield precise information of the error condition depending on the specific error.
The parameters, which a specific standard CTMS error can transport to the caller are listed below as well.
The Status
The "status" property generally carries the actual HTTP status of the response. This is not true for "plural" results, such as responses to bulk requests, which regularity end with 200 - OK.
The Content Type
The Content-Type header of an error response has the value application/vnd.avid.problem+json.
Doing the error check
When we face an error condition encapsulated into a structured error of an HTTP response, we can analyze the error and its context solely from the information in the response:
if (response.getErrorCode().endsWith("CTMS/INVALID_PARAMETER")) {
// Aha! A pretty precise condition.
final String erroneousParameterName = response.getParams().get("parameterName");
LOGGER.warn("{} has an invalid value: {}", erroneousParameterName, response.getMessage());
}
Structured error codes should be used for erroneous results of all ordinary ("singular") CTMS requests, and also in requests with a potentially "plural" result, such as bulk requests. A response of a bulk request should be able to carry a mix of result-items and structured-error-items. Also commands should make use of structured errors.
Standard CTMS Error Codes
Error Code |
HTTP Status Code |
Description |
---|---|---|
CTMS/COMMAND_ABORTED |
200 |
The execution of the command was aborted by the backend. |
CTMS/COMMAND_CANCELED |
200 |
The execution of the command was canceled from the client-side. |
CTMS/ARRAY_OBJECTS_SUPPORTED _ONLY_FOR_MULTI_VALUE |
400 |
It was tried to pass an array object, were only singular values can be passed. |
CTMS/BAD_REQUEST |
400 |
|
CTMS/COMMAND_BAD_ARGUMENT |
400 |
Any sort of invalid argument. Parameters:
|
CTMS/EMPTY_BODY |
400 |
|
CTMS/FILE_EMPTY |
400 |
|
CTMS/FILE_TOO_LARGE |
400 |
Parameters:
|
CTMS/INVALID_ATTRIBUTES |
400 |
|
CTMS/INVALID_BODY |
400 |
The body is wrongly formatted/cannot be parsed by the service. |
CTMS/INVALID_HEADER |
400 |
Parameters:
|
CTMS/INVALID_MULTI_VALUE_STRUCTURE |
400 |
|
CTMS/INVALID_PARAMETER |
400 |
An invalid argument of a query parameter or an invalid value for a property in the body (if the invalid property in the body can be clearly identified, this error code can provide more information than CTMS/INVALID_BODY, because the parameterName can be specified). Parameters:
|
CTMS/INVALID_RELATION |
400 |
E.g. issued, if the referenced relation does not exist. |
CTMS/INVALID_RESERVATION |
400 |
Issued, if reservations are handled wrongly. |
CTMS/INVALID_SETTING |
400 |
E.g. issued, if a setting could not be deleted. |
CTMS/INVALID_STATUS_PROPERTY |
400 |
E.g. issued, if a status property is unrecognized. |
CTMS/INVALID_TIMEBASED |
400 |
E.g. issued, if trying to create or modify timebased data on assets it is not supported. |
CTMS/MISSING_HEADER |
400 |
Parameters:
|
CTMS/PARENT_FOLDER_NOT_FOUND |
400 |
Parameters:
|
CTMS/UNKNOWN_DATA_FORMAT |
400 |
|
CTMS/UNKNOWN_RELATION_DIRECTION |
400 |
|
CTMS/UNKNOWN_RELATION_TYPE |
400 |
|
CTMS/UNSUPPORTED_MULTI_VALUE_BASE_TYPE |
400 |
|
CTMS/ACCESS_DENIED |
403 |
|
CTMS/COMMAND_REJECTED |
403 |
|
CTMS/DELETION_FORBIDDEN |
403 |
|
CTMS/INSUFFICIENT_PERMISSIONS |
403 |
|
CTMS/INVALID_CREDENTIALS |
403 |
|
CTMS/DELETION_NOT_ALLOWED |
403 |
E.g. issued, if the asset or the folder containing the item in question is reserved. |
CTMS/ASSET_NOT_FOUND |
404 |
Parameters:
|
CTMS/CHECKIN_DATA_FILE_NOT_FOUND |
404 |
|
CTMS/CHECKIN_IMAGE_FILE_NOT_FOUND |
404 |
|
CTMS/COLLECTION_NOT_FOUND |
404 |
|
CTMS/COMMAND_NOT_FOUND |
404 |
|
CTMS/FILE_LOCATION_NOT_FOUND |
404 |
|
CTMS/FOLDER_NOT_FOUND |
404 |
Parameters:
|
CTMS/ITEM_NOT_FOUND |
404 |
Parameters:
|
CTMS/SETTINGS_SECTION_NOT_FOUND |
404 |
|
CTMS/TAXONOMY_ENTRY_NOT_FOUND |
404 |
Parameters:
|
CTMS/TAXONOMY_NOT_FOUND |
404 |
Parameters:
|
CTMS/THUMBNAIL_NOT_FOUND |
404 |
|
CTMS/COMMAND_EXISTS |
409 |
|
CTMS/ITEM_EXISTS |
409 |
Parameters:
|
CTMS/COMMAND_ERROR |
500 |
|
CTMS/COMMAND_TIMED_OUT |
504 |