Ошибки

Единый плоский конверт ошибки, который возвращает каждый эндпоинт, коды статусов рядом с ним и какие отказы имеет смысл повторять.

У каждого ответа с ошибкой одна и та же плоская форма:

{
  "error": "VALIDATION_ERROR",
  "message": "name is required",
  "details": [{ "field": "name", "issue": "required" }]
}

error — стабильный машиночитаемый код, message — текст для человека, details — необязательное поле. Конверт никогда не бывает вложенным и никогда не несёт флаг success: ветвитесь по HTTP-статусу и по error, а не по наличию полезной нагрузки.

Коды статусов

статус	значение
400	запрос повреждён или в нём не хватает поля
401	не аутентифицирован — токен отсутствует, повреждён, истёк или отозван
403	аутентифицирован, но не разрешено; в публичном API это почти всегда `INSUFFICIENT_SCOPE`
404	ресурса не существует
409	конфликт — конкурентное обновление потеряно либо ресурс уже в запрошенном состоянии
422	запрос корректен по форме, но не может быть обработан
429	превышен лимит частоты запросов для токена
500	непредвиденный сбой на нашей стороне
503	сервис ещё запускается — можно повторить

`INSUFFICIENT_SCOPE` — отказ, под который надо проектировать

Поскольку публичный API работает на запрет по умолчанию, самая частая ошибка работающей интеграции — не провал валидации, а отказ по области доступа. Токен достаёт только те сущности и действия, под которые он выпущен, а всё остальное отвечает 403 INSUFFICIENT_SCOPE с сущностью и действием, названными в сообщении. Модель областей доступа и точное тело ответа — в разделе Аутентификация.

Считайте это ошибкой конфигурации, а не временным сбоем: для данной пары «токен и эндпоинт» она детерминирована и исчезает только после перевыпуска токена с недостающей областью доступа.

Что имеет смысл повторять

429 и 503 временные. Отступите и повторите.
5xx, кроме 503, могут быть временными; повторяйте с задержкой и потолком.
400, 401, 403, 404, 409, 422 — нет. Тот же запрос упадёт так же. В частности, 403 INSUFFICIENT_SCOPE — это токен, который нужно перевыпустить, а повторы лишь расходуют ваш лимит частоты.

Списки кодов в справочнике — образец, а не закрытое множество

Отдельные эндпоинты в справочнике описывают коды ошибок, которые действительно отдаёт сервис этого эндпоинта. Эти списки — образец того, что вы вероятно увидите, а не исчерпывающее объединение: клиент обязан обрабатывать нераспознанное значение error, опираясь на HTTP-статус.

См. также

Лимиты частоты — подробно про 429 и Retry-After
Вебхуки — собственные статусы входящего получателя, которые используют тот же конверт
Версионирование и вывод из эксплуатации — почему новые коды error могут появляться без уведомления