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	Payload	Description
entity_not_found	EntityNotFound	The requested entity does not exist.
not_found		The requested resource does not exist.
deleted_entity_operation		The requested operation cannot be performed on a deleted entity.
not_deleted_entity_operation		The requested operation cannot be performed on a non-deleted entity.
access_denied		The user does not have permission to perform the requested operation.
validation_error		The request data failed validation.
missing_version_header		The Scale-Version header is missing from the request.
invalid_version		The version header that is received is not in the list of supported versions.
unsupported_version		The request version is valid, but the current operation is not supporting this version.
deprecated_version		The requested version is deprecated and should not be used.
unknown_error		An unknown error occurred.

Entity Not Found error

Code: entity_not_found.
Type: EntityNotFound.

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