Ошибки

Один формат отказа на все методы и номер запроса для поддержки.

Формат

Любой отказ выглядит одинаково:

{
  "error": {
    "code": "validation_failed",
    "message": "Request validation failed",
    "details": [{ "field": "limit", "message": "Must be an integer 1…100" }],
    "request_id": "9b1f2c3d-4e5f-6a7b-8c9d-0e1f2a3b4c5d"
  }
}

Разбирайте code, а не текст. message написан для человека и может меняться; code — часть контракта.

Поле details есть не всегда. У ошибок проверки это список полей, у нехватки прав — название нужного права, у превышения лимита — какой именно лимит исчерпан.

Коды

HTTP	`code`	Что произошло
401	`unauthorized`	Ключа нет или он мёртв
402	`plan_required`	Публичный API не входит в тариф проекта
403	`insufficient_scope`	У ключа нет нужного права
404	`not_found`	Объекта нет или он в другом проекте
409	`conflict`	Действие противоречит текущему состоянию
422	`validation_failed`	Неверные параметры или тело запроса
422	`idempotency_mismatch`	Тот же `Idempotency-Key` с другим телом
429	`rate_limited`	Превышен лимит запросов
500	`internal`	Наша ошибка

Объекта из чужого проекта не существует — так и отвечаем, 404. Отдельного «нет доступа» нет: 403 означает нехватку права у ключа, а не чужой объект.

Номер запроса

Каждый ответ, удачный или нет, несёт заголовок X-Request-Id. Тот же номер лежит внутри тела ошибки. Назовите его в письме в поддержку — по нему мы найдём именно ваш запрос.

Как обрабатывать

401 и 403 — ошибка настройки. Повторять бессмысленно, нужно чинить ключ или его права.
404 — объекта нет. Для синхронизации это часто нормально: запись могли удалить.
409 — состояние изменилось. Перечитайте объект и решите, что делать.
422 — ошибка в запросе. Повторять с тем же телом бессмысленно.
429 — подождите столько секунд, сколько указано в Retry-After, и повторите.
500 и таймауты — повторяйте с растущей паузой. Если запрос был записывающим, повторяйте с тем же `Idempotency-Key`, чтобы не создать дубль.

← Назад: Постраничная выдача

Дальше: Лимиты запросов →