03. Error Handling

Business Errors

The error-handling system is designed to provide standardized and informative messages about business and validation errors. This mechanism manages specific errors (such as data conflicts or missing resources) and explains the reason for the error.

Validation Errors: These occur when invalid data is entered into certain fields. For example, entering a phone number in a field that requires a valid email address.

Resource Errors: These are related to invalid parameters, invalid operations, existing or non-existent entities, etc. For example, attempting to add a device with data that already belongs to an existing device.

A list of validation and resource errors is provided in the following section

Validation Errors

The validation error is also standardized and provides customized messages for such errors within the system. It maps validation issues identified in input fields.

Most possible errors are predefined. Examples include:

ARRAY_MUST_NOT_BE_EMPTY: The array field must not be empty.

FIELD_MAX_LENGTH_EXCEEDED: The field has exceeded the maximum character limit.

FIELD_MUST_BE_INTEGER: The field must contain an integer.

Each error code is represented by a constant and mapped to a specific message, ensuring uniformity and standardization.

By default, the error message includes the field containing the invalid data and, when applicable, the expected format for that specific case.

Most validation messages follow this format, with some exceptions:
"Field {dataField} must be {fieldValidation}"

For example, in a registration context, if an email is not in the expected format, such as "123456789" entered in some email field, the expected error message would be:

"Field 123456789 must be a valid email"
This message specifies that the input does not conform to the required email format, and would return the following response body:

{
  "status": "error",
  "error": {
    "error_code": "INVALID_EMAIL_FORMAT",
    "message": "Field 123456789 must be a valid email",
    "field": "email"
  }
}

List of Validation Errors

Error Code	Description	Example of Returned Message
ARRAY_MUST_NOT_BE_EMPTY	The array must not be empty	Field `{fieldName}` must not be empty
FIELD_MAX_LENGTH_EXCEEDED	The field exceeds the maximum character limit	Field `{fieldName}` must have at most `{maxLength}` characters
FIELD_MIN_LENGTH_NOT_MET	The field does not meet the minimum character limit	Field `{fieldName}` must have at least `{minLength}` characters
FIELD_MUST_BE_BOOLEAN	The field must be a boolean value	Field `{fieldName}` must be a boolean
FIELD_MUST_BE_EMAIL	The field must contain a valid email	Field `{fieldName}` must be a valid email
FIELD_MUST_BE_INTEGER	The field must be an integer	Field `{fieldName}` must be an integer
FIELD_MUST_BE_NUMERIC	The field must be a number	Field `{fieldName}` must be a number
FIELD_MUST_BE_PHONE_NUMBER	The field must contain a valid phone number	Field `{fieldName}` must be a valid phone number
FIELD_MUST_BE_STRING	The field must be a string	Field `{fieldName}` must be a string
FIELD_MUST_NOT_BE_EMPTY	The field must not be empty	Field `{fieldName}` must not be empty
INVALID_DATE_FORMAT	The field must contain a valid date in the specified format	Field `{fieldName}` must be a valid date string in the format `{dateFormat}`
INVALID_URL_FORMAT	The field must contain a valid URL	Field `{fieldName}` must be a valid URL
NUMBER_MUST_BE_POSITIVE	The field must be a positive number	Field `{fieldName}` must be a positive number
UNSUPPORTED_ENUM_VALUE	The field must contain a valid value from the allowed set	Field `{fieldName}` must be one of the following enum values: `{enumValues}`
VALUE_ABOVE_MAXIMUM	The field value exceeds the maximum allowed limit	Value of field `{fieldName}` is above the maximum allowed (`{maxValue}`)
VALUE_BELOW_MINIMUM	The field value is below the minimum allowed limit	Value of field `{fieldName}` is below the minimum allowed (`{minValue}`)
FIELD_MUST_BE_ARRAY	The field must be an array	Field `{fieldName}` must be an array
FIELD_MUST_BE_UUID	The field must contain a valid UUID	Field `{fieldName}` must be a valid UUID
FIELD_MUST_BE_DEFINED	The field must be defined	Field `{fieldName}` must be defined

Resource Errors

Resource errors are similarly standardized and provide customized messages to indicate conflicts or issues with existing resources in the system. These errors occur when operations cannot be completed due to conflicts, missing resources, or other resource-related constraints.

Each error code is represented by a constant and mapped to a specific message, ensuring uniformity and clarity.

By default, the error message identifies the resource or field causing the issue and provides additional context about the nature of the conflict or error.

Most resource error messages follow a format similar to this:
"{Entity} already exists with this {Field}"

For example if a client attempts to create a tracker with an IMEI that already exists in the system, the expected conflict error message would be:

"TRACKER already exists with this IMEI""

The response body would return the following:

{
    "status": "error",
    "error": {
        "error_code": "ENTITY_WITH_FIELD_ALREADY_EXISTS",
        "message": "TRACKER already exists with this IMEI",
        "details": {
            "field": "TRAKCER",
            "value": {
                "trackerName": "tracker test",
                "trackerDesc": "tracker description",
                "imei": "123-ABC-4567",
                "status": "active"
            }
        }
    }
}

Request Response Codes

Code	Description
200	Operation completed successfully.
201	Creation completed successfully.
400	Error in request parameters or entity not found.
401	User not authorized or not logged in.
409	Conflict with an existing entity or relationship.
422	Issue with parameters in the database request.
500	Other errors.

List of Resource Errors

Error Code	Description	HTTP Status Code
INVALID_PARAMETERS	There were one or more validation errors in the request	400 Bad Request
ENTITY_WITH_FIELD_ALREADY_EXISTS	`{entity}` already exists with this `{field}`	409 Conflict
ENTITY_WITH_FIELD_NOT_FOUND	`{entity}` not found with field `{field}`	400 Bad Request
FIELD_MUST_BE_OF_TYPE	`{field}` must be of type `{type}`	400 Bad Request
FIELD_MUST_NOT_BE_EMPTY	`{field}` must not be empty	400 Bad Request
INSTANCE_NOT_FOUND	Instance not found	400 Bad Request
ENTITY_NOT_FOUND	`{entityName} {entity} not found`	400 Bad Request
ENTITY_ALREADY_EXISTS	`{entityName} already exists`	409 Conflict
QUERY_FAILED	Database query error occurred	422 Unprocessable Entity
REQUEST_FAILED	Error processing request	500 Internal Server Error

Business Errors#

Validation Errors#

List of Validation Errors#

Resource Errors#