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

Структура ошибочного ответа от 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-метода вызывающая сторона получила ошибочный ответ, рекомендуется каким-либо образом зафиксировать (см. errorId).: либо отобразить пользователю, либо сохранить. Только по ID ошибки техническая поддержка сможет быстро определить детали и причину возникновения ошибки, и, следовательно, решить вопрос, связанный с её появлением.

Поиск документации