Сообщения об ошибках REST API

Обзор

Сообщение об ошибке имеет следующий формат

Пример
{
  "error_code" :: integer,
  "error_message" :: string
  "error_details" :: object
}

  • error_code - Код категории ошибки.

  • error_message - Текст ошибки.

  • error_details - Опциональное поле, добавляется при наличии дополнительных параметров. Например, название поля, код сообщения об ошибке, или установленный таймаут.

Коды категорий (error_code)

Коды error_code могут иметь следующие значения:

  • 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 - требуется подтверждение операции, см. Коды ответов файловых разделов (fs/targets);

  • 1501 - internal_error;

  • 1502 - exception;

  • 1503 - throw;

  • 1504 - exit;

  • 1505 - other category;

  • 1506 - unknown category.

Коды сообщений (error_details.msg_code)

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

Расширенные коды сообщений об ошибке msg_code уникальные коды для конкретных сообщений об ошибке и служат для отображения в веб-приложении текста:

Сообщения общего характера:

  • 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 и OpenId Connect 1.0 аутентификация:

  • 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.

Отправка приглашений пользователям на подключение к системе:

  • 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.

Самостоятельная регистрация пользователей:

  • 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.

Восстановление пароля учетной записи пользователя:

  • 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.

Смена пароля учетной записи пользователя:

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

  • 15402 - Old password is wrong.

Коды ответов файловых разделов (fs/targets)

Эндпойнты файловых разделов сообщают об отказе HTTP-кодом ответа; в теле приходит сообщение об ошибке в описанном выше формате.

HTTP-код Когда возвращается

405 Method Not Allowed

Заливка методом POST в несуществующий каталог: каталог, в который производится заливка, должен существовать. Чтобы разместить файл вместе с недостающими каталогами пути, используется метод PUT.

Удаление корня раздела и обращение методом, который раздел не поддерживает.

409 Conflict

  • Каталог не пуст, а удаление запрошено без параметра recursive.

  • Путь назначения при перемещении занят, а параметр overwrite не указан.

  • Ключ подтверждения не подошёл. Сервер может вернуть в этом случае и повторный 428; оба ответа обрабатываются одинаково, см. Операции над каталогами.

  • Объём рекурсивной операции превышает границы limits.recursive_delete из описания разделов. Операция в этом случае не выполняется вовсе.

  • Имя файла, у которого часть после последнего ! совпадает с методом раздела, отвергнуто при записи: такой файл был бы недостижим по API, см. Нестандартные методы в пути.

411 Length Required

Тело запроса пришло без заголовка Content-Length — например, с Transfer-Encoding: chunked. Объём такого тела нечем проверить до приёма, поэтому запрос отвергается, не читая тело. Относится ко всем методам заливки: POST, PUT и UPLOADZIP.

413 Request Entity Too Large

Тело запроса достигло предела. Предел здесь — первый отклоняемый размер, а не последний допустимый: тело, равное пределу, уже отвергается.

  • Заливка файла методами POST и PUT: предел — max_file_size раздела из описания разделов, по умолчанию 536 870 912 байт.

  • Заливка архива методом UPLOADZIP: предел — 2 000 000 000 байт, см. Скачивание и заливка каталога архивом. Он относится к телу запроса, то есть к самому архиву; объём распакованного содержимого ограничен отдельно, см. 422 ниже.

Размер проверяется по заголовку Content-Length до чтения тела, поэтому отказ приходит до передачи содержимого и на диск не попадает ничего. В теле ответа — сообщение об ошибке с error_code = 1410 (limited), называющее и предел раздела, и фактический размер запроса.

422 Unprocessable Entity

Отвергнут архив. Архив отвергается целиком: на диск не попадает ни один файл из него, включая безопасные. Перечень требований — Требования к содержимому архива.

  • Архив содержит записи с .., абсолютные пути или символические ссылки за пределы архива.

  • Суммарный объём распакованного содержимого архива превышает 2 000 000 000 байт. Предел здесь — последний допустимый размер: объём, равный ему, проходит. Этим сравнение отличается от проверки тела запроса в строке 413.

  • Отдельная запись архива превышает max_file_size раздела: в распакованном виде она не прошла бы ограничение на размер файла. Сравнение такое же — запись размером ровно в предел раздела принимается.

Оба предела объёма определяются по оглавлению архива до распаковки, поэтому отказ приходит, не начиная её. В теле ответа — сообщение с error_code = 1406; если дело в отдельной записи, сообщение называет её имя.

428 Precondition Required

Операция требует подтверждения, error_code = 1428. Возвращается на первый запрос рекурсивного удаления и очистки непустого каталога; сама операция при этом не выполняется.

Требуется подтверждение операции (1428)

Ответ 428 Precondition Required с кодом 1428 дополнительно содержит в теле:

  • confirmation_key - ключ, который передаётся параметром key во втором запросе;

  • expires_in - число секунд, оставшихся до истечения ключа;

  • entries - объём предстоящей операции: число файлов (files) и каталогов (directories), суммарный размер в байтах (bytes) и признак превышения границ (truncated).

Пример
{
  "error_code" : 1428,
  "error_message" : "Confirmation required",
  "confirmation_key" : "493769f214f028c0a415888026352bbf",
  "expires_in" : 77,
  "entries" : {
    "files" : 1,
    "directories" : 0,
    "bytes" : 1,
    "truncated" : false
  }
}

Порядок работы с ключом: Операции над каталогами.

  • Персонализация
  • Увеличить шрифт
  • Уменьшить шрифт