Все разделыОсновы

Формат ошибок

Обновлено 23 октября 2026 г. · 2 мин чтения

Любая ошибка приходит в одном виде. code — для программы, он не меняется. message — для человека, по-русски. request_id — номер запроса для поддержки, он же в заголовке X-Request-Id.

Ответ 422

{
  "error": {
    "code": "validation_error",
    "message": "Поле message обязательно.",
    "details": { "field": "message" },
    "request_id": "req_3f9c2a7d1e6b4a8c0d2e5f71"
  }
}

Коды

HTTP	`code`	Что случилось и что делать
400	`bad_request`	Неверный параметр: курсор, `limit`, время не в ISO 8601, неизвестный статус в фильтре
400	`invalid_json`	Тело — не JSON-объект. Проверьте `Content-Type: application/json`
401	`unauthorized`	Нет ключа в заголовке
401	`invalid_token`	Ключ или токен не найден, отозван, сотрудник отключён
401	`token_expired`	Срок ключа или токена истёк. Токен OAuth — обновите по `refresh_token`
402	`payment_required`	Лицензия компании закончилась. Первые три дня работает только чтение
403	`insufficient_scope`	У ключа нет права, оно — в `details.required_scope`
403	`forbidden`	У сотрудника ключа нет права в кабинете
404	`not_found`	Объекта нет или он чужой — ответ одинаковый
409	`conflict`	Дубль клиента, подписка выключена, лимит подписок
409	`idempotency_in_progress`	Запрос с этим `Idempotency-Key` ещё выполняется
413	`bad_request`	Тело больше 256 КБ
422	`validation_error`	Поле не прошло проверку, оно — в `details.field`
422	`idempotency_key_reused`	`Idempotency-Key` уже был с другим телом
423	`locked`	Компания запросила удаление — новые действия остановлены
429	`rate_limited`	Лимит запросов, ждите `Retry-After` (лимиты)
500	`internal_error`	Сбой у нас. Повторите позже; если повторяется — напишите с `request_id`

Что повторять

Повторяйте 429 после Retry-After, 5xx и обрывы сети — с тем же Idempotency-Key у POST (подробнее).
Не повторяйте 4xx, кроме 409 idempotency_in_progress: ответ не изменится, пока не исправите запрос.

Ошибки OAuth-эндпоинтов /api/oauth/token и /api/oauth/revoke — в формате RFC 6749: { "error", "error_description" } (токены).

Статья помогла?

Не нашли ответ? Напишите нам

Поддержка ответит в рабочее время.

Вы сотрудник «Дескус»?Изменить статью в Дескусе