Обработка ошибок

Любая ошибка от Толоки характеризуется HTTP статусом ответа и телом ответа с уточняющей информацией. Ошибки самодокументирующиеся, то есть из них должно быть понятно, в чём причина.

Пример ошибки c HTTP статусом 409:

{
  "request_id": "337d68d1-974d-42b1-a2d0-6234f6373eed",
  "code": "INAPPROPRIATE_STATUS",
  "message": "This or related resource is in inappropriate status, operation is not allowed",
  "payload": {
    "appropriate_statuses": [
      "OPEN",
      "CLOSED"
    ]
  }
}

В тексте каждой ошибки есть поля:

• request_id — внутренний идентификатор HTTP-запроса, в котором произошла ошибка. Его необходимо указывать при обращении в поддержку.
• code — строковый код ошибки. Ошибки, характерные для разных операций, имеют одинаковые коды. Для одного и того же HTTP статуса могут использоваться разные коды ошибок. Специфичные ошибки для конкретных операций имеют свои уникальные коды.
• message — более подробное описание ошибки. Содержание поля может быть разным для одного и того же кода ошибки.
• payload — дополнительная информация об ошибке. Например, поле из запроса и причина ошибки в нём. Это поле необязательное и может отсутствовать.

Список распространённых ошибок

Ниже приведены HTTP статусы, описывающие классы ошибок, с примерами распространённых ошибок.

400 — ошибка в данных, которые переданы в запросе.

{
  "code": "VALIDATION_ERROR",
  "message": "Validation failed",
}

403 — нет прав для выполнения операции.

{
  "code": "ACCESS_DENIED",
  "message": "Access denied"
}

404 — запрашиваемый объект не существует.

{
  "code": "DOES_NOT_EXIST",
  "message": "There are no results for such parameters"
}

409 — операция не может быть выполнена исходя из её логики. Например, нельзя открыть пул, находящийся в архиве.

{
  "code": "CONFLICT_STATE",
  "message": "Conflict state"
}

429 — превышено допустимое количество запросов в единицу времени.

{
  "code": "TOO_MANY_REQUESTS",
  "message": "Too many requests"
}

500 — непредвиденная ошибка в сервисе. Для ее решения необходимо [обратиться в поддержку]({{ requester-help }) с указанием request_id.

{
  "code": "INTERNAL_ERROR",
  "message": "Internal Error"
}

503 — сервис временно недоступен, запрос можно повторить через некоторое время.

{
  "code": "REMOTE_SERVICE_UNAVAILABLE",
  "message": "Service is temporary unavailable"
}