Спецификация стандартизированных ответов адаптеров ErisPulse
Tip
Когда читать этот документ: когда вы реализуете в адаптере возвращаемые значения call_api / Send / Request, требуется убедиться, что структура ответа и коды возврата соответствуют стандарту ErisPulse, или разобраться в значении конкретного retcode — сверяйтесь с этим документом. Если это не нужно — пропустите.
1. Описание
Зачем нужна эта спецификация?
Для обеспечения единообразия возвращаемых значений интерфейсов отправки на различных платформах и совместимости с OneBot12 адаптеры ErisPulse для формата ответов API используют стандарт структуры ответов на отправку сообщений, определённый OneBot12.
Однако протокол ErisPulse имеет некоторые особые определения:
- Среди базовых полей message_id является обязательным, но в стандарте OneBot12 такого поля нет
- В возвращаемое содержимое необходимо добавить поле {platform_name}_raw для хранения исходных данных ответа
2. Базовая структура ответа
Все ответы на действия (action) должны содержать следующие базовые поля:
| Имя поля | Тип данных | Обязательное | Описание |
|---|---|---|---|
| status | string | Да | Статус выполнения, должен быть "ok" или "failed" |
| retcode | int64 | Да | Код возврата, соответствует правилам кодов возврата OneBot12 |
| data | any | Да | Данные ответа; при успехе содержит результат запроса, при неудаче — null |
| message_id | string | Да | Идентификатор сообщения, используемый для идентификации; при отсутствии — пустая строка |
| message | string | Да | Сообщение об ошибке; при успехе — пустая строка |
| {platform_name}_raw | any | Нет | Исходные данные ответа |
Необязательные поля:
| Имя поля | Тип данных | Обязательное | Описание |
|---|---|---|---|
| echo | string | Нет | Если запрос содержит поле echo, возвращается без изменений |
3. Полная спецификация полей
3.1 Общие поля
Пример успешного ответа
{
"status": "ok",
"retcode": 0,
"data": {
"message_id": "1234",
"time": 1632847927.599013
},
"message_id": "1234",
"message": "",
"echo": "1234",
"telegram_raw": {...}
}
Пример ответа при ошибке
{
"status": "failed",
"retcode": 10003,
"data": null,
"message_id": "",
"message": "Отсутствует обязательный параметр: user_id",
"echo": "1234",
"telegram_raw": {...}
}
3.2 Спецификация кодов возврата
0 Успех (OK)
- 0: Успех (OK)
1xxxx Ошибка запроса действия (Request Error)
| Код ошибки | Название ошибки | Описание |
|---|---|---|
| 10001 | Bad Request | Некорректный запрос действия |
| 10002 | Unsupported Action | Неподдерживаемый запрос действия |
| 10003 | Bad Param | Некорректные параметры запроса действия |
| 10004 | Unsupported Param | Неподдерживаемые параметры запроса действия |
| 10005 | Unsupported Segment | Неподдерживаемый тип сегмента сообщения |
| 10006 | Bad Segment Data | Некорректные данные сегмента сообщения |
| 10007 | Unsupported Segment Data | Неподдерживаемые данные сегмента сообщения |
| 10101 | Who Am I | Не указана учётная запись бота |
| 10102 | Unknown Self | Неизвестная учётная запись бота |
2xxxx Ошибка обработчика действия (Handler Error)
| Код ошибки | Название ошибки | Описание |
|---|---|---|
| 20001 | Bad Handler | Ошибка реализации обработчика действия |
| 20002 | Internal Handler Error | Исключение во время выполнения обработчика действия |
3xxxx Ошибка выполнения действия (Execution Error)
| Диапазон кодов ошибок | Тип ошибки | Описание |
|---|---|---|
| 31xxx | Database Error | Ошибка базы данных |
| 32xxx | Filesystem Error | Ошибка файловой системы |
| 33xxx | Network Error | Сетевая ошибка |
| 34xxx | Platform Error | Ошибка платформы бота |
| 35xxx | Logic Error | Ошибка логики действия |
| 36xxx | I Am Tired | Реализация решила объявить забастовку |
Зарезервированные сегменты ошибок
- 4xxxx, 5xxxx: зарезервированные сегменты, использовать не следует
- 6xxxx–9xxxx: прочие сегменты ошибок, для пользовательских нужд реализации
4. Требования к реализации
- Все ответы должны содержать поля status, retcode, data и message
- Если запрос содержит непустое поле echo, ответ должен содержать поле echo с тем же значением
- Коды возврата должны строго соответствовать спецификации OneBot12
- Сообщения об ошибках (message) должны быть человекочитаемым описанием
4.1 Помощники построения ответа: make_response / make_error
Для построения стандартных ответов адаптерам следует использовать два помощника из BaseAdapter, без необходимости вручную писать dict:
# Успех (send / call_api / _do_accept и все места, возвращающие стандартный ответ)
return self.make_response(
data=result, # Данные ответа
message_id=result.get("message_id", ""),
raw=result, # Исходный ответ платформы → автоматически попадает в поле {platform}_raw
)
# Неудача (status всегда "failed")
return self.make_error(
retcode=34100, # По умолчанию 34600 (SDK Failure); для ошибок платформы следует передавать собственный код 34xxx
message="Отклонено контролем рисков платформы",
raw=response,
)
| Помощник | Сигнатура | Семантика |
|---|---|---|
make_response |
(*, status="ok", retcode=0, data=None, message_id="", message="", raw=None) |
Собирает структуру по стандарту; если raw не None, автоматически добавляет ключ {platform}_raw (имя платформы берётся из self._platform) |
make_error |
(retcode=34600, message="", raw=None) |
Сокращение для make_response(status="failed", ...) |
Ручное написание эквивалентного dict также допустимо (достаточно совпадения структуры); ценность помощников — в корректной конкатенации имени платформы для
{platform}_rawи в том, что полнота полей не будет нарушена.
5. Расширения спецификации
ErisPulse добавил следующие расширения поверх стандартной структуры ответа OneBot12:
5.1 Обязательное поле message_id
В стандарте OneBot12 message_id находится внутри объекта data и не является обязательным. ErisPulse поднял его до обязательного поля верхнего уровня:
- Если
message_idполучить невозможно, следует установить пустую строку"" - Гарантирует, что
message_idприсутствует всегда; модулям не нужно выполнять проверку на null
Важно различать обе стороны: поднятие на верхний уровень в этом разделе относится только к ответам на действия (исходящим).
message_idво входящих событиях message является обязательным полем верхнего уровня согласно базовой спецификации OneBot12, см. стандарт преобразования событий.
5.2 Поле исходного ответа {platform}_raw
Возвращаемое значение должно содержать поле {platform}_raw, хранящее полную копию исходных данных ответа платформы:
{
"status": "ok",
"retcode": 0,
"data": {"message_id": "1234", "time": 1632847927},
"message_id": "1234",
"message": "",
"telegram_raw": {
"ok": true,
"result": {"message_id": 1234, "date": 1632847927, ...}
}
}
Требования:
{platform}_rawдолжен быть глубокой копией исходного ответа, а не ссылкойplatformдолжно точно совпадать с именем платформы, указанным при регистрации адаптера (с учётом регистра)- Информация об ошибках из исходного ответа также должна сохраняться для упрощения отладки
5.3 Расширенные коды возврата фреймворка (кастомизация трёх младших разрядов сегмента ошибок платформы 34xxx)
Спецификация OneBot12 позволяет реализациям определять три младших разряда 3xxxx по своему усмотрению. Семантика 34xxx — Platform Error
(ошибка платформы бота, например неудача из-за ограничений платформы). Внутри 34xxx используется послойно по зонам ответственности:
| Сегмент трёх младших разрядов | Принадлежность | Назначение |
|---|---|---|
340xx |
Реализация адаптера | Семейство операций запросов (Request Not Found / Already Handled / Not Supported / Permission Denied, см. request-action-spec §7) |
341xx–345xx |
Реализация адаптера | Ошибки со стороны платформы: права доступа / контроль рисков / ограничения учётной записи и т. п. (реализация определяет три младших разряда самостоятельно, исходная ошибка помещается в {platform}_raw) |
346xx |
Фреймворк ErisPulse (зарезервировано) | Перехват самим фреймворком и общие неудачи; адаптерам/модулям не занимать |
347xx–349xx |
Реализация адаптера | Прочие ошибки выполнения на стороне платформы |
Коды 346xx, используемые в настоящее время фреймворком ErisPulse:
| Код ошибки | Название ошибки | Описание |
|---|---|---|
| 34600 | SDK Failure | Общая неудача фреймворка (код возврата по умолчанию для make_error()) |
| 34601 | Action Denied | Исходящее действие запрещено областью видимости (scope.actions), вызов не был инициирован, этот ответ возвращается сразу |
Разграничение ответственности:
34601— фреймворк перехватывает до вызова (модуль вообще не имеет права инициировать действие); коды платформы34004/34xxx— действие уже отправлено, но платформа его отклонила (например, у Bot нет прав или сработал контроль рисков). При диагностике проблем с правами модулям следует проверять оба случая: сначала смотреть34601(собственный модуль заблокирован scope), затем34xxx(ограничения на стороне платформы).
Структура ответа — стандартный ответ об ошибке из §2:
{
"status": "failed",
"retcode": 34601,
"data": null,
"message_id": "",
"message": "action 'send' denied by scope.actions"
}
5.4 Чек-лист реализации адаптера
- Содержит поля
status,retcode,data,message_id,message - Коды возврата следуют спецификации OneBot12 (подробнее в §3.2)
-
message_idприсутствует всегда (если получить невозможно — пустая строка) -
{platform}_rawсодержит исходные данные ответа платформы
6. Примечания
- Для кодов ошибок 3xxxx три младших разряда могут определяться реализацией самостоятельно
- Избегайте использования зарезервированных сегментов ошибок (4xxxx, 5xxxx)
34600/34601— зарезервированные коды фреймворка ErisPulse (см. §5.3); адаптерам/модулям следует избегать их использования- Сообщения об ошибках должны быть краткими и понятными для упрощения отладки
Следующие шаги
- Справочник при реализации возвращаемых значений для каждого DSL: стандарт действий API (поле data стандартных действий), спецификация операций запросов (расширение 34001-34004 для операций запросов), спецификация методов отправки (семантика деградации при неудаче отправки)
- Диагностика сбоев, связанных с правами: сначала смотрите
34601(модуль заблокирован scope, фреймворк перехватывает до вызова, см. §5.3), затем34xxx(действие отправлено, но отклонено на стороне платформы)