REST API error messages

Overview

An error message has the following format

Example
{
  "error_code" :: integer,
  "error_message" :: string
  "error_details" :: object
}
  • error_code - Error category code.

  • error_message - Error text.

  • error_details - Optional field added when additional parameters are present. For example, the field name, error message code, or the configured timeout.

Category codes (error_code)

error_code codes can have the following values:

  • 1401 - access_denied;

  • 1402 - already_exists;

  • 1403 - not_implemented;

  • 1404 - not_found;

  • 1405 - invalid_request;

  • 1406 - invalid_operation;

  • 1407 - unauthorized;

  • 1408 - not_loaded;

  • 1409 - operation_failed;

  • 1410 - limited;

  • 1411 - license_restriction;

  • 1412 - config_restriction;

  • 1413 - invalid_params;

  • 1414 - timeout;

  • 1428 - operation confirmation required, see File section response codes (fs/targets);

  • 1501 - internal_error;

  • 1502 - exception;

  • 1503 - throw;

  • 1504 - exit;

  • 1506 - unknown category.

Message codes (error_details.msg_code)

Example 1
{
  "error_code": 1501,
  "error_message": "pwd contains invalid symbols. Expected: A-Za-z0-9_-.~!",
  "error_details":{
    "field": "pwd",
    "msg_code": 10006
  }
}
Example 2
{
  "error_code": 1501,
  "error_message": "Wait for 120 sec and try again",
  "error_details":{
    "timer": 120,
    "msg_code": 10201
  }
}

Extended error message codes msg_code are unique codes for specific error messages and are used to display text in the web application:

General messages:

  • 10001 - Domain not found.

  • 10002 - User not found.

  • 10003 - Master domain not available.

  • 10004 - Domain not available.

  • 10005 - Internal DC error

  • 10006 - (Some DC external error)

  • 10007 - Internal DMS error

  • 10008 - (Some DMS external error)

  • 10009 - Request is already expired

  • 10010 - Auth failure

  • 10011 - (Some auth external error)

  • 10012 - Access denied

  • 10013 - Invalid domain

  • 10014 - Access denied by configuration.

  • 10015 - Domain request timeout.

  • 10016 - Access denied by IAM (route not found).

  • 10017 - Access denied by IAM (method not allowed).

  • 10018 - Access denied by IAM (role mismatch).

  • 10019 - Access denied by IAM (…​).

  • 10020 - Token auth disabled.

  • 10021 - Token auth failure.

  • 10022 - Session already exists.

  • 10023 - Cookie not set.

  • 10024 - Cookie session has expired.

  • 10025 - Session not found. Required params not found. Expected: 'td', 'login', 'pwd'.

  • 10026 - Session prerequisites must not be overriden by 'td' and 'login' params.

  • 10027 - Unrecognized 'session_type'. Expected 'token', 'token_clone_cookie' or 'cookie'.

  • 10028 - Invalid json in body.

  • 10029 - JSON object expected.

  • 10030 - Too large body. Expected max 524288 bytes.

  • 10031 - Too large json in '…​'. Must be less than 10MB.

  • 10032 - Invalid json in '…​'.

  • 10033 - No response from remote handler node.

  • 10034 - API WS nodes not found or unavailable on remote site(s) handling this domain.

  • 10035 - Prepare response error. See log.

  • 10036 - Access denied to route …​

  • 10037 - Invalid path. Route unavailable.

  • 10038 - Access denied. Only administrator is allowed to perform request.

  • 10039 - Redirect by session.

  • 10060 - Invalid content. Expected object.

  • 10061 - login already exists

  • 10062 - email already used by another user

  • 10063 - phonenumber already used by another user

  • 10064 - phonenumber already used by sipuser

  • 10065 - phonenumber already used by sipgroup

  • 10066 - pwd must be string

  • 10067 - name must be less than 1000 symbols

  • 10068 - login must be less than 100 symbols

  • 10069 - pwd must be less than 100 symbols

  • 10070 - login contains invalid symbols. Expected: A-Za-z0-9(_-.~!*^\"'?|$#&%)

  • 10071 - pwd contains invalid symbols. Expected: A-Za-z0-9(_-.~!)

  • 10072 - pwd doesn’t satisfy policy. <CUSTOM PASSWORD POLICY DESCRIPTION>

  • 10099 - (Some other external error)

  • 10101 - Domain is not defined (expected: 'domain').

  • 10102 - Login is not defined (expected: 'login').

  • 10103 - Name is not defined (expected: 'name').

  • 10104 - Email is not defined (expected: 'email').

  • 10105 - Password not defined (expected: 'pwd').

  • 10106 - Current password not defined (expected: 'current_pwd').

  • 10107 - New password not defined (expected: 'new_pwd').

  • 10108 - Key is not defined (expected: 'key').

  • 10109 - UserId is not defined (expected: 'userid').

  • 10201 - Wait for XXX sec and try again.

OAuth 2.0 and OpenId Connect 1.0 authentication:

  • 10301 - Invalid OAuth provider.

  • 10302 - Invalid OAuth authentication status.

  • 10303 - OAuth authentication failure.

  • 10304 - Invalid id. OAuth request not exists or expired on enter.

  • 10305 - Invalid id. Request not exists or expired on receiver.

Sending invitations to users to connect to the system:

  • 15103 - Invalid id. Invite not exists or expired.

  • 15104 - User email is not defined.

  • 15105 - Operation is not available. Request your administrator to change password or setup email.

User self-registration:

  • 15201 - Domain doesn’t allow to self register.

  • 15202 - Only unauthorized user allowed to self register.

  • 15203 - Invalid id. Self registration request not exists or expired.

  • 15204 - Operation is not available. Request your administrator to change password or setup email.

User account password recovery:

  • 15301 - Operation is not available. Request your administrator to change password or setup email.

  • 15303 - Invalid id. Request not exists or expired.

  • 15306 - Key is not valid email address.

  • 15304 - Email not found. Request your administrator to change password or setup email.

  • 15305 - User’s email is not set. Request your administrator to change password or setup email.

  • 15306 - OAuth 2.0 authentication is used.

Changing a user account password:

  • 15401 - Operation is not available. Request your administrator to change password or setup email.

  • 15402 - Old password is wrong.

File section response codes (fs/targets)

File section endpoints report a refusal with an HTTP response code; the body contains an error message in the format described above.

HTTP code When returned

405 Method Not Allowed

Upload with the POST method into a non-existent directory: the directory into which the upload is performed must exist. To place a file together with missing path directories, the PUT method is used.

Deleting the section root and calling a method the section does not support.

409 Conflict

  • The directory is not empty, and deletion was requested without the recursive parameter.

  • The destination path is occupied during a move, and the overwrite parameter is not specified.

  • The confirmation key did not match. The server may also return a repeated 428 in this case; both responses are handled the same way, see Directory operations.

  • The volume of the recursive operation exceeds the limits.recursive_delete bounds from the section description. In this case the operation is not performed at all.

  • A file name whose part after the last ! matches the section method was rejected on write: such a file would be unreachable via the API, see Non-standard methods in the path.

411 Length Required

The request body arrived without the Content-Length header — for example, with Transfer-Encoding: chunked. The volume of such a body cannot be checked before reception, so the request is rejected without reading the body. Applies to all upload methods: POST, PUT, and UPLOADZIP.

413 Request Entity Too Large

The request body reached the limit. The limit here is the first rejected size, not the last allowed one: a body equal to the limit is already rejected.

  • Uploading a file with POST and PUT: the limit is the section max_file_size from the section description, by default 536 870 912 bytes.

  • Uploading an archive with UPLOADZIP: the limit is 2 000 000 000 bytes, see Downloading and uploading a directory as an archive. It applies to the request body, i.e., the archive itself; the volume of unpacked content is limited separately, see 422 below.

The size is checked by the Content-Length header before reading the body, so the refusal arrives before content transfer and nothing reaches the disk. The response body contains an error message with error_code = 1410 (limited), naming both the section limit and the actual request size.

422 Unprocessable Entity

The archive is rejected. The archive is rejected entirely: none of its files reach the disk, including safe ones. The list of requirements is in Archive content requirements.

  • The archive contains entries with .., absolute paths, or symbolic links outside the archive.

  • The total volume of unpacked archive content exceeds 2 000 000 000 bytes. The limit here is the last allowed size: a volume equal to it passes. This comparison differs from the request body check in the 413 row.

  • A single archive entry exceeds the section max_file_size: unpacked, it would not pass the file size limit. The comparison is the same — an entry exactly at the section limit is accepted.

Both volume limits are determined from the archive table of contents before unpacking, so the refusal arrives without starting it. The response body contains a message with error_code = 1406; if the issue is a single entry, the message names it.

428 Precondition Required

The operation requires confirmation, error_code = 1428. Returned on the first request for recursive deletion and clearing of a non-empty directory; the operation itself is not performed.

Operation confirmation required (1428)

The 428 Precondition Required response with code 1428 additionally contains in the body:

  • confirmation_key - key passed as the key parameter in the second request;

  • expires_in - number of seconds remaining until the key expires;

  • entries - volume of the upcoming operation: number of files (files) and directories (directories), total size in bytes (bytes), and an indication of exceeding bounds (truncated).

Example
{
  "error_code" : 1428,
  "error_message" : "Confirmation required",
  "confirmation_key" : "493769f214f028c0a415888026352bbf",
  "expires_in" : 77,
  "entries" : {
    "files" : 1,
    "directories" : 0,
    "bytes" : 1,
    "truncated" : false
  }
}

Procedure for working with the key: Directory operations.