В данном разделе будут описаны особенности полей тела ответа при ошибках выполнения методов, а также приведены примеры различных ошибок с разным наполнением

Структура ошибочного ответа

Структура ошибочного ответа от API включает в себя обязательные поля и может включать поля с дополнительной информацией.

Пример ошибочного ответа от API - 404 Not Found

``` 
{
   "result": false,
   "errorId": "a8b5db7c-5153-4cd6-9376-5c70f6429ab4",
   "errorMessage": "Документ с заданным ID не найден.",
   "errorCode": "13.562",
   "operationCode": "11.181",
   "errorData": {
       "documentId": "219e96b8-1180-4bbe-97e0-97a3ea6098b4"
   }
}
```

Описание полей:

result - Операция выполнена успешно?
Тип: boolean
Обязательное?: Да
Пример: false
Пояснение: В случае с ошибочными ответами всегда принимает значение false.
errorId - Идентификатор ошибки.
Тип: string
Формат: uuid
Обязательное?: Да
Пример: "a8b5db7c-5153-4cd6-9376-5c70f6429ab4"
Пояснение: С помощью этого поля техническая поддержка сможет найти внутренние детали об ошибке, что позволит быстро разобраться в ситуации и причинах её возникновения.

errorMessage - Сообщение об ошибке.
Тип: string
Обязательное?: Да
Пример: "Документ с заданным ID не найден."
Пояснение: Данное поле содержит краткое описание причины возникновения ошибки.
errorCode - Код произошедшей ошибки.
Тип: string
Обязательное?: Да
Пример: "13.562"
Пояснение: Это поле предназначено для того, чтобы вызывающая сторона могла формально определить ошибку, зная её код, и определенным образом на неё отреагировать. Для обработки определённых ошибок и формирования сообщений об ошибках на стороне клиента можно опираться на код ошибки и на данные об ошибке, если код ошибки предусматривает возврат этих данных.
operationCode - Код операции, вызываемой API-методом.
Тип: string
Обязательное?: Да
Пример: "11.181"
errorData - Дополнительные данные об ошибке.

Тип: object
Обязательное?: Нет

Пример:
{ "documentId": "219e96b8-1180-4bbe-97e0-97a3ea6098b4" }
Пояснение: Структура объекта и типы данных в полях внутри объекта определяется конкретной ошибкой. В данном поле возвращаются дополнительные формализованные данные о произошедшей ошибке, если произошедшая ошибка предусматривает возврат этих данных.

Виды и примеры ошибочных ответов от API

Ошибки клиента

Все формализованные ошибки входят в группу кодов ответов 4xx, предназначенных для указания ошибок клиента. Ниже приведены примеры тел ошибочных ответов от API с различным наполнением.

Пример ответа без дополнительных данных об ошибке - 401 Unauthorized

``` 
{
   "result": false,
   "errorId": "72b55807-ed45-4af0-916e-9fa97fd0da51",
   "errorMessage": "Невалидный API токен.",
   "errorCode": "11.006",
   "operationCode": "11.100"
}
```

Пример ответа с дополнительными формализованными данными об ошибке - 400 Bad Request

``` 
{
    "result": false,
    "errorId": "602b88d8-86a5-4054-8082-0797fddd3e3b",
    "errorMessage": 
        "Заданный JSON не соответствует ожидаемому формату.",
    "errorCode": "11.021",
    "operationCode": "11.181",
    "errorData": {
        "path": "documents[0]"
    }
}
```

Пример ответа с дополнительными формализованными данными об ошибке - 403 Forbidden

``` 
{
    "result": false,
    "errorId": "e36dd708-4cc8-402f-94fd-e6a7a02d2921",
    "errorMessage": "Нет прав выполнять запрошенную операцию.",
    "errorCode": "10.000",
    "operationCode": "11.082",
    "errorData": {
        "permission": "EMPLOYEE_POSITIONS"
    }
}
```

Ошибки на сервере

При неуспешном выполнении API-запроса может также вернуться ответ с кодом ошибки 500 Internal Server Error, которая возникает из-за внутренней проблемы сервера при невозможности обработки запроса.

По таким ошибкам клиент не может самостоятельно определить причину возникновения ошибки. В таком случае необходимо обратиться в техподдержку и сообщить идентификатор ошибки (см. errorId).

Пример ответа от API при ошибке на сервере - 500 Internal Server Error

``` 
{
   "result": false,
   "errorId": "3c67ae53-9617-48e1-ab69-0657116f8585",
   "errorMessage": "Внутренняя ошибка на сервере.",
   "errorCode": "11.000",
   "operationCode": "21.100"
}
```

Структура ошибочного ответа

Виды и примеры ошибочных ответов от API

Ошибки клиента

Ошибки на сервере

Рекомендация по обработке ошибочных ответов