API Responses

HTTP status codes, errors and request validation

You must validate requests and return HTTP status codes within the 4xx range if an error is caused by the client, and within the 5xx range if an error is caused by the server. The JSON response body will include an array of validation/error messages.

For example an error might return:

• Error Type: A machine readable and consistent type e.g. INTERNAL_ERROR, ACCOUNT_USER
• Error Feedback: A human readable explaining the error type.
• Exception: Exception data if application

Validation errors will return:

• Field: Associated model field for which the validation error is associated e.g DocumentDate
• Criteria: Description of qualifying valid criteria. Dates must be in the format dd/MMM/YYYY e.g. 30/JUL/1966
• Validation Error Type: A machine readable and consistent validation error type e.g. INVALID_DATE_FORMAT
• Message: A human readable message explaining the error e.g. The date format entered is invalid.

Our standard validation codes

Validation Error Type	Description
REQUIRED_FIELD_MISSING	Required data missing
MAX_LENGTH_EXCEEDED	The data supplied exceeded the allowed length.
INVALID_DATE_FORMAT	The date supplied is provided in an invalid format.
INVALID_DATE_RANGE	The date supplied is outside of the permitted range. For example if the date specified is in the past yet past values aren’t allowed.
INVALID_NUMBER_FORMAT	A number provided is in an invalid format. For example if decimal numbers weren’t permitted.
INVALID_NUMBER_RANGE	The number provided is out of the allowed range. For example if negative numbers weren’t permitted.
INVALID_FORMAT	General format error.
ID_VALUE_MISMATCH	Some requests may support ID and value. For example UserId and Email, before using the ID (UserId) and Value (Email) must correlate.
METADATA_RULE_VIOLATION	Metadata submitted doesn’t pass business rule validation. For example an Artifact may imply a specific Sub-Artifact, attempting to supply an invalid Sub-Artifact would imply a rule violation.
UNKNOWN_RESOURCE	Request refers to resources which do not exist or do not have access to see.
UNSUPPORTED_FILTER_SYNTAX	The filter parameter supplied has syntax not supported. For example document querying does not currently support OR based filtering.
INVALID_FILTER_SYNTAX	The filter parameter supplied is invalid. For example “name eq 'John Smith’” is valid however “name = ‘John Smith’” is invalid syntax.
UNSUPPORTED_ORDERBY_SYNTAX	The order by parameter supplied has a syntax not supported. For example some requests won’t support multiple column ordering.
INVALID_ORDERBY_SYNTAX	The order by parameter supplied is invalid. For example “name asc” is valid however “name ascending” would be invalid.
DUPLICATE_METADATA	Duplicate metadata items have been supplied whereby only one is permitted.
METADATA_ATTRIBUTE_NOT_FOUND	The metadata supplied does not match a known metadata attribute within the system.
INVALID_METADATA_OPTION	The metadata supplied isn't a valid option given other metadata restraints.
METADATA_SECURITY_VIOLATION	Metadata supplied is valid but not allowed based on the security configuration.

Our standard error codes

Code	Error Type	Description
401	AUTHENTICATION_FAILURE	The supplied information could not be authenticated. I.e. username/password incorrect
401	ACCOUNT_DISABLED	The account attempting to authenticate is disabled.
401	ACCOUNT_LOCKED	The account attempting to authenticate is locked.
401	ACCOUNT_PASSWORD_CHANGE_REQUIRED	The account attempting to authenticate is requires a password change.
401	INVALID_TOKEN	The JWT authentication token supplied is invalid.
403	NOT_AUTHORIZED	Access is not permitted based on the supplied authentication token.
404	RESOURCE_NOT_FOUND	The resource requested was not found
500	RESTORE_POINT_OPEN	Action cannot be undertaken as a restore point is open.
500	INTERNAL_ERROR	An error occurred e.g. unhandled error, network or database connectivity issues.