Ошибки

Единый формат ошибок, коды состояния и лимит запросов.

Все ошибки приходят в едином формате JSON:

{
  "detail": "Человекочитаемое описание, что пошло не так",
  "code": "machine_readable_code"
}

detail — текст для логов и разработчика.
code — стабильный машиночитаемый код; ветвитесь в интеграции по нему, а не по тексту detail.

Коды состояния HTTP

Статус	Когда
`400`	Неверный запрос: битые параметры, невалидное тело.
`401`	Нет заголовка `X-API-Key` или ключ неверный.
`403`	Ключа не хватает по скоупу (напр. запись `read_only`-ключом) или доступ к чужому ресурсу.
`404`	Ресурс не найден (или не принадлежит вам).
`409`	Конфликт — например, дубликат.
`422`	Ошибка валидации входных данных.
`429`	Превышен лимит запросов (300/мин на ключ) — повторите с задержкой.
`5xx`	Ошибка на нашей стороне — стоит повторить с экспоненциальным backoff.

Ретрайте 429 и 5xx с экспоненциальной задержкой; не ретрайте 4xx (кроме 429).
Логируйте code — по нему мы сможем быстрее помочь.
Лимит запросов — 300/мин на ключ; см. Аутентификация.

Каталог машиночитаемых code расширяется. Если в интеграции важен конкретный код, которого здесь нет — напишите нам, зафиксируем его в этом разделе.