ErisPulse Adapter Standardized Return Specification

1. Description

Why does this specification exist?

To ensure the uniformity of API response formats across different platforms and maintain compatibility with OneBot12, the ErisPulse adapter adopts the message sending return structure standard defined by OneBot12.

However, the ErisPulse protocol has some special definitions:

• 1. In the base fields, message_id is required, but this field does not exist in the OneBot12 standard.
• 2. The response content needs to include a {platform_name}_raw field to store the raw response data.

2. Basic Return Structure

All action responses must include the following basic fields:

Optional fields:

3. Full Field Specification

3.1 Common Fields

Successful Response Example

{
    "status": "ok",
    "retcode": 0,
    "data": {
        "message_id": "1234",
        "time": 1632847927.599013
    },
    "message_id": "1234",
    "message": "",
    "echo": "1234",
    "telegram_raw": {...}
}

Failed Response Example

{
    "status": "failed",
    "retcode": 10003,
    "data": null,
    "message_id": "",
    "message": "Missing required parameter: user_id",
    "echo": "1234",
    "telegram_raw": {...}
}

3.2 Return Code Specification

0 Success (OK)

• 0: Success (OK)

1xxxx Request Error

2xxxx Handler Error

3xxxx Execution Error

Reserved Error Ranges

• 4xxxx, 5xxxx: Reserved ranges, should not be used
• 6xxxx–9xxxx: Other error ranges, for custom implementation use

4. Implementation Requirements

1. All responses must contain the fields: status, retcode, data, and message.
2. When the request contains a non-empty echo field, the response must include an echo field with the same value.
3. Return codes must strictly follow the OneBot12 specification.
4. Error messages (message) should be human-readable descriptions.

5. Extension Specifications

ErisPulse extends the OneBot12 standard return structure as follows:

5.1 message_id Required Field

In the OneBot12 standard, message_id is located within the data object and is not mandatory. ErisPulse elevates it to a required top-level field:

• When message_id cannot be obtained, it should be set as an empty string ""
• Ensure message_id always exists, so modules do not need to perform null checks

5.2 {platform}_raw Raw Response Field

The return value should include the {platform}_raw field, which stores a complete copy of the raw response data from the platform:

{
    "status": "ok",
    "retcode": 0,
    "data": {"message_id": "1234", "time": 1632847927},
    "message_id": "1234",
    "message": "",
    "telegram_raw": {
        "ok": true,
        "result": {"message_id": 1234, "date": 1632847927, ...}
    }
}

Requirements:

• {platform}_raw must be a deep copy of the original response, not a reference
• platform must exactly match the platform name registered by the adapter (case-sensitive)
• Error information from the original response should also be retained for debugging purposes

5.3 Framework Extension Return Codes (Custom Low Three Digits in the 34xxx Platform Error Segment)

The OneBot12 specification allows implementations to define custom low three digits of 3xxxx. The 34xxx segment semantics are Platform Error (robot platform error, such as failures caused by platform restrictions). The 34xxx segment is used hierarchically according to responsibilities:

ErisPulse framework currently uses the 346xx codes:

Responsibility distinction: 34601 is framework-level interception before the call (the module has no right to initiate the action); 34004 / 34xxx platform codes are actions already sent but rejected by the platform (e.g., Bot lacks permission, is restricted). When modules check for permission issues, they should check both types: first check 34601 (the module's own scope is disabled), then check 34xxx (platform-side restrictions).

The return structure is the standard failure response as defined in §2:

{
    "status": "failed",
    "retcode": 34601,
    "data": null,
    "message_id": "",
    "message": "action 'send' denied by scope.actions"
}

5.4 Adapter Implementation Checklist

• Include status, retcode, data, message_id, message fields
• Return codes follow the OneBot12 specification (see §3.2)
• message_id always exists (set as empty string if unavailable)
• {platform}_raw contains the raw response data from the platform

6. Notes

• For error codes in the 3xxxx range, the last three digits can be defined by the implementation.
• Avoid using reserved error ranges (4xxxx, 5xxxx).
• 34600 / 34601 are reserved error codes for the ErisPulse framework (see §5.3); adapters/modules should avoid using them.
• Error messages should be concise and clear for easier debugging.