Common error codes

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.pam/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.pam/CTMS/INVALID_PARAMETER". As can be seen the code as such has some segments separated by /.

The first segment, avid.pam, 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:

  • parameterName: the name of the parameter carrying the invalid argument

CTMS/EMPTY_BODY

400

CTMS/FILE_EMPTY

400

CTMS/FILE_TOO_LARGE

400

Parameters:

  • name: the name of the file in question

  • max: the max size of a file

CTMS/INVALID_ATTRIBUTES

400

CTMS/INVALID_BODY

400

The body is wrongly formatted/cannot be parsed by the service.

CTMS/INVALID_HEADER

400

Parameters:

  • name: the name of the header in question

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:

  • parameterName: the name of the parameter carrying the invalid argument

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:

  • name: the name of the header in question

CTMS/PARENT_FOLDER_NOT_FOUND

400

Parameters:

  • id: the id of the item without parent

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/ASSET_NOT_FOUND

404

Parameters:

  • id: the id of the missing asset

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:

  • id: the id of the missing folder

CTMS/ITEM_NOT_FOUND

404

Parameters:

  • id: the id of the missing item

CTMS/SETTINGS_SECTION_NOT_FOUND

404

CTMS/TAXONOMY_ENTRY_NOT_FOUND

404

Parameters:

  • taxonomyid: the id of the taxonomy

  • taxonomyentryid: the id of the missing taxonomy entry

CTMS/TAXONOMY_NOT_FOUND

404

Parameters:

  • id: the id of the missing taxonomy

CTMS/THUMBNAIL_NOT_FOUND

404

CTMS/DELETION_NOT_ALLOWED

405

E.g. issued, if the asset in question is reserved.

CTMS/COMMAND_EXISTS

409

CTMS/ITEM_EXISTS

409

Parameters:

  • id: the id of the already existing item

  • target: the location in which the item is already existing

CTMS/COMMAND_ERROR

500

CTMS/COMMAND_TIMED_OUT

504