Коды ошибок и что с ними делать

Что означает код, кто его возвращает и какое действие пользователя или интеграции снимает проблему.

Как читать код

Сообщение всегда состоит из двух частей: что случилось и что делать. Код — машинное имя той же ситуации.

Пример ответа

{ "error": "SCOPE_REQUIRED", "message": "this token does not carry board.edit" }

Тело всегда одно и то же: машиночитаемый error и человеческое message. message объясняет, что именно не так, но не содержит секретов и текста доски.

Что делать с кодом

Ответ	Действие
`401`	обновить сессию или токен; повторять запрос как есть бессмысленно
`403`	получить право или scope; повтор не поможет
`404`	проверить идентификатор и доступ к доске
`409 STALE`	перечитать доску, обновить `ifVersion` и повторить
`409 JOB_NOT_FOUND`	начать задание экспорта заново
`422`	исправить входные данные, имя поля есть в сообщении
`503 NOT_PERSISTED`	повторить с тем же `Idempotency-Key`

Доступ

Код	Статус	Что значит	Что делать
`AUTH_REQUIRED`	401	нет сессии	войти в аккаунт
`ACCOUNT_REQUIRED`	403	аккаунта нет, а действие требует прав	войти или использовать токен интеграции
`FORBIDDEN`	403	роль не даёт нужного права	запросить роль у владельца доски
`RESOURCE_NOT_AVAILABLE`	404	доски нет или она не видна	проверить ссылку и доступ
`SCOPE_REQUIRED`	403	у токена интеграции нет нужного scope	выпустить токен с нужным scope
`INTEGRATION_TOKEN_UNKNOWN`	401	токена не существует	проверить значение токена
`INTEGRATION_TOKEN_REVOKED`	401	токен отозван	выпустить новый
`INTEGRATION_TOKEN_EXPIRED`	401	срок токена истёк	выпустить новый
`PASSWORD_REQUIRED`	401	у ссылки есть пароль	ввести пароль
`LINK_INACTIVE`	404	ссылка выключена или истекла	включить ссылку или запросить новую
`ALREADY_CLAIMED`	409	доска уже имеет владельца	работать через владельца
`EMAIL_MISMATCH`	422	приглашение выдано на другую почту	войти под приглашённым аккаунтом
`BACKUP_REQUIRED`	403	для замены обсуждения нет права бэкапа	запросить `board.backup`

Команды и запись

Код	Статус	Что значит	Что делать
`BAD_INPUT`	422	входные данные не прошли проверку	исправить поле, имя указано в сообщении
`IDEMPOTENCY_KEY_REQUIRED`	400	нет `Idempotency-Key`	отправить заголовок
`STALE`	409	доска изменилась с момента чтения версии	перечитать и повторить
`NOT_PERSISTED`	503	изменение в памяти, но не записано	повторить с тем же ключом
`OBJECT_NOT_FOUND`	404	объекта нет	перечитать доску
`CONNECTOR_EXISTS`	409	между парой уже есть связь	изменить существующую
`SELF_LOOP`	422	связь объекта с самим собой	выбрать другой конец
`OBJECT_LOCKED`	409	объект заблокирован	снять замок автором или менеджером
`LOCKED_BY_OTHER`	409	замок принадлежит другому человеку	попросить автора или менеджера снять его
`COMMENT_FORBIDDEN`	403	роль не даёт писать в обсуждение	запросить `board.comment`
`COMMENT_BODY_REQUIRED`	422	пустой или слишком длинный комментарий	ввести от 1 до 4000 символов
`COMMENT_ANCHOR_REQUIRED`	422	у треда нет объекта или точки	выбрать объект или место на доске
`THREAD_NOT_FOUND`	404	треда нет или он с другой доски	перечитать список
`COMMENT_NOT_FOUND`	404	сообщения нет	перечитать тред

Экспорт

Код	Статус	Что значит	Что делать
`BAD_SCOPE`	422	неизвестный скоуп	выбрать `selection`, `frame` или `board`
`BAD_FORMAT`	422	неизвестный формат задания	выбрать `png` или `pdf`; бэкап — отдельный запрос
`JOB_NOT_FOUND`	409	задание экспорта истекло	начать экспорт заново

Куда дальше

Экспорт и бэкап — что требуется для экспорта и бэкапа.