ErisPulse ErisPulse
インタラクティブ版で開く →
このページのセクション
静的ミラーです。内容はインタラクティブ版が正となります インタラクティブ版で開く →

ErisPulse アダプターの標準化された返却値仕様

Tip

この記事を読むタイミング:アダプター内で call_api / Send / Request の返り値を実装する際に、返却値の構造と返却コードが ErisPulse の標準に準拠しているか確認する必要がある場合、または特定の retcode の意味を確認したい場合に、本記事を参照してください。必要がない場合は飛ばしてください。

1. 説明

なぜこの規格があるのでしょうか?

各プラットフォームの送信インターフェースが一貫性とOneBot12との互換性を確保するため、ErisPulseアダプターはAPIレスポンス形式においてOneBot12が定義するメッセージ送信返却構造の標準を採用しています。

ただしErisPulseのプロトコルにはいくつかの特殊な定義があります:

    1. 基本フィールドにおいて、message_idは必須ですが、OneBot12の標準にはこのフィールドはありません。
    1. 返却内容には、{platform_name}_raw フィールドを追加する必要があります。このフィールドには、元のレスポンスデータを格納します。

2. 基礎レスポンス構造

すべてのアクションレスポンスには、以下の基本フィールドを含める必要があります。

フィールド名 データ型 必須 説明
status string はい 実行ステータス。"ok"または"failed"のいずれかに設定する必要があります
retcode int64 はい 戻り値コード。OneBot12の戻り値コード規則に従います
data any はい レスポンスデータ。成功時はリクエスト結果を含み、失敗時はnull
message_id string はい メッセージID。メッセージを識別するためのもので、存在しない場合は空文字列
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. 実装要件

  1. すべてのレスポンスは、status、retcode、data、message フィールドを含む必要があります。
  2. リクエストに非空の echo フィールドが含まれている場合、レスポンスには同じ値の echo フィールドが含まれている必要があります。
  3. 戻り値コードは OneBot12 規格に厳密に従う必要があります。
  4. エラーメッセージ(message)は人間に読みやすい説明である必要があります。

4.1 レスポンス構築ヘルパー:make_response / make_error

アダプタは、BaseAdapter 上の 2 つのヘルパーを使用して標準レスポンスを一貫して構築します。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 イベントの message_id は 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 プラットフォームエラーセグメントの下3桁カスタム)

OneBot12 規格では、実装者が 3xxxx の下3桁をカスタムに使用できます。34xxx の意味は Platform Error(ロボットプラットフォームエラー、例えばプラットフォーム制限により失敗した場合)です。34xxx 内部では、役割に応じて以下の層に分けて使用します:

下3桁セグメント 所属 用途
340xx アダプタ実装 リクエスト操作族(Request Not Found / Already Handled / Not Supported / Permission Denied、request-action-spec §7 参照)
341xx~345xx アダプタ実装 プラットフォーム側の権限 / リスク管理 / アカウント制限等のエラー(実装者が下3桁を独自に定義し、原始エラーは {platform}_raw に格納)
346xx ErisPulse フレームワーク(予約済み) フレームワーク自身によるブロックと一般的な失敗、アダプタ/モジュールは使用しない
347xx~349xx アダプタ実装 その他のプラットフォーム実行エラー

ErisPulse フレームワークで現在使用している 346xx エラーコードは以下の通りです:

エラーコード エラーネーム 説明
34600 SDK Failure フレームワークの一般的な失敗(make_error() のデフォルト返却コード)
34601 Action Denied 出力アクションがスコープ scope.actions により禁止されているため、呼び出しは行われず、直接この応答を返す

役割の区別:34601 はフレームワークが呼び出し前にブロックした場合(モジュールはそもそもアクションを発行する資格がない)です。一方、34004 / 34xxx プラットフォームコードはアクションは発行されたがプラットフォームが拒否した場合(Bot に権限がない、リスク管理対象など)です。モジュールが権限問題を判断する際には、この2つを同時にチェックする必要があります:まず 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エラーコードについては、下位3桁は実装側で独自に定義可能
  • 予約エラーセグメント(4xxxx、5xxxx)の使用を避けること
  • 34600 / 34601 は ErisPulse フレームワークが予約するコード(§5.3参照)であり、アダプタ/モジュールは使用しないこと
  • エラーメッセージは簡潔かつ明瞭にし、デバッグに役立つようにすること

次のステップ

  • 各DSLの戻り値に対応する照会:APIアクション標準(標準アクションのdataフィールド)、リクエスト操作規格(リクエスト操作の34001-34004拡張)、送信メソッド規格(送信失敗時の降格意味)
  • 権限関連の失敗のトラブルシューティング:まず34601(モジュールがscopeによって禁止されている、フレームワークが呼び出し前にブロックする、§5.3を参照)、次に34xxx(アクションは発行されたが、プラットフォーム側で拒否された)を確認する