Errors

Conventional HTTP status codes are used to indicate the success or failure of an API request:

• 2xx codes indicate success.
• 4xx codes indicate an error that failed given the information provided (e.g., a required parameter was omitted, etc.).
  Errors that could be handled programmatically (e.g., an entity does not exist) include an error code that explains the error reported.
• 5xx codes indicate an error within Scale servers (these are rare).

HTTP Code	Reason	Description
200	OK	Everything worked as expected.
400	Bad Request	The request was unacceptable, often due to missing a required parameter.
401	Unauthorized	No valid authentication provided.
403	Forbidden	The provided identity doesn't have permissions to perform the request.
404	Not Found	The requested resource doesn't exist.
422	Unprocessable Content	The parameters were valid but the request failed (e.g., an entity with the same name already exists).
429	Too Many Requests	Too many requests hit the API too quickly.

Attributes of the error response object:

• code - A short string that uniquely identifies the error. See Error Codes for more information.
• message - A human-readable message providing more details about the error.
• traceId - A unique identifier of the request that caused the error to be used for debugging purposes.
• details (Optional) - An object that provides more detailed information about the error. The structure of this object is not fixed and can change depending on the error.

Example

HTTP 422 Unprocessable Content
{
    "code": "entity_not_unique",
    "message": "Entity violates one or more uniqueness constraints.",
    "traceId": "00-49b5250fc418ce6cf5086647a2d6ff62-81a414175e6d8090-01",
    "details": {
      "entityType": "User",
      "entityId": "12345"
    }
}

Error Codes

Errors include a code field that can be used to programmatically identify the error.

Below is a list of error codes, along with additional detailed payload (if any) and their descriptions

Code	Description
access_denied	The user does not have permission to perform the requested operation.
deleted_entity_operation	The requested operation cannot be performed on a deleted entity.
deprecated_version	The requested version is deprecated and should not be used.
entity_not_found	The requested entity does not exist. See the EntityNotFound object in the response for additional details.
invalid_username_or_password	The username or password provided in the request are invalid.
invalid_version	The version header that is received is not in the list of supported versions.
missing_version_header	The Scale-Version header is missing from the request.
not_deleted_entity_operation	The requested operation cannot be performed on a non-deleted entity.
not_found	The requested resource does not exist.
too_many_requests	Too many requests were sent in a given amount of time. See Rate Limiting for more information.
too_many_results_found	Too many results found. Please narrow down your search criteria.
unit_does_not_belong_to_site	The specified unit does not belong to the specified site.
unknown_error	An unknown error occurred.
unsupported_version	The request version is valid, but the current operation is not supporting this version.
validation_error	The request data failed validation.

Entity Not Found error

Code: entity_not_found.

Additional details in the response include:

• entityType - The type of the entity that was not found.
• entityId - The identifier of the entity that was requested but not found.