Как читать код
Сообщение всегда состоит из двух частей: что случилось и что делать. Код — машинное имя той же ситуации.
Пример ответа
{ "error": "SCOPE_REQUIRED", "message": "this token does not carry board.edit" }
Тело всегда одно и то же: машиночитаемый error и человеческое message. message
объясняет, что именно не так, но не содержит секретов и текста комнаты.
Что делать с кодом
| Ответ | Действие |
|---|---|
401 |
обновить сессию или токен; повторять запрос как есть бессмысленно |
403 |
получить право или scope; повтор не поможет |
403 UNCLAIMED |
у комнаты нет владельца: нужен не доступ, а закрепление |
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 | ссылка выключена или истекла | включить ссылку или запросить новую |
UNCLAIMED |
403 | у комнаты нет владельца | закрепить комнату за собой или назначить владельца |
CLAIM_REJECTED |
403 | неверный или отсутствующий токен закрепления, если у комнаты он задан | открыть ссылку с верным токеном |
ALREADY_CLAIMED |
409 | у комнаты уже есть владелец | работать через владельца; повторное закрепление отклоняется |
ORG_REQUIRED |
409 | у аккаунта нет организации | создать организацию и повторить закрепление |
EMAIL_MISMATCH |
422 | приглашение выдано на другую почту | войти под приглашённым аккаунтом |
BACKUP_REQUIRED |
403 | для замены обсуждения нет права бэкапа | запросить board.backup |
Комната без владельца
GET /boards/:id/access для такой комнаты отвечает 200 с allowed: false, reason: "UNCLAIMED" и пустым списком capabilities. Этого достаточно, чтобы показать экран закрепления, но не содержимое: все остальные маршруты, кроме закрепления, отвечают 403 UNCLAIMED, сокет отклоняет подключение, в списке комнат и в корзине её нет.
Закрепление — POST /boards/:id/claim с необязательным {token}. Комната закрепляется за вошедшим человеком, архивная метка снимается, организация и команда берутся из его аккаунта; без организации или команды ответ — 409 ORG_REQUIRED или 409 TEAM_REQUIRED. После закрепления действуют обычные роли и публичная ссылка.
Команды и запись
| Код | Статус | Что значит | Что делать |
|---|---|---|---|
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 | сообщения нет | перечитать тред |
Профиль, организация и комната
| Код | Статус | Что значит | Что делать |
|---|---|---|---|
HANDLE_TAKEN |
409 | ник уже занят | выбрать другой |
BAD_HANDLE |
422 | ник не по правилам | 3–32 символа, латиница, цифры, ., -, _; начинается и заканчивается буквой или цифрой |
HANDLE_TOO_SHORT / HANDLE_TOO_LONG |
422 | длина ника вне 3–32 | исправить длину |
HANDLE_RESERVED |
422 | служебный ник | выбрать другой |
NAME_REQUIRED / NAME_TOO_LONG |
422 | имя пустое или длиннее 80 | ввести имя 1–80 символов |
ICON_TOO_LONG / BAD_ICON |
422 | эмодзи слишком длинный или с управляющими символами | выбрать один эмодзи |
EMAIL_TAKEN |
409 | почта уже зарегистрирована | войти или восстановить доступ |
WEAK_PASSWORD |
422 | пароль короче 10 символов | выбрать пароль длиннее |
RATE_LIMITED |
429 | слишком много попыток | подождать и повторить |
ORG_NAME_REQUIRED |
422 | у организации нет названия | ввести название |
TEAM_NAME_REQUIRED / TEAM_NAME_TAKEN |
422/409 | название команды пустое или занято | выбрать другое название |
TEAM_IN_USE |
409 | на команду ссылаются комнаты или гранты | сначала переназначить их |
TEAM_REQUIRED |
409/422 | в организации нет команды: 409 при закреплении, 422 при создании комнаты | создать команду |
ALREADY_ARCHIVED / NOT_ARCHIVED |
409 | комната уже в корзине или уже не в ней | перечитать состояние |
BOARD_CREATE_FORBIDDEN |
403 | роль не даёт создавать комнаты | запросить активное участие в организации |
Экспорт
| Код | Статус | Что значит | Что делать |
|---|---|---|---|
BAD_SCOPE |
422 | неизвестный скоуп | выбрать selection, frame или board |
BAD_FORMAT |
422 | неизвестный формат задания | выбрать png или pdf; бэкап — отдельный запрос |
JOB_NOT_FOUND |
409 | задание экспорта истекло | начать экспорт заново |
Куда дальше
Экспорт и бэкап — что требуется для экспорта и бэкапа. Доступ к комнате — закрепление комнаты без владельца и роли.