Errors

Common error envelope

Most command failures are emitted as a live event whose type ends with _error:

{
  "type": "chat_update",
  "userbot_id": 1,
  "payload": {
    "userbot_id": 1,
    "type": "send_message_error",
    "error": "chat_id is required"
  }
}

Error sources in current code

Handler-level validation

Examples visible in handlers:

• chat_id is required in members handlers
• explicit *_error events for streaming command failures
• refresh_self_profile_error on unexpected exceptions

Service-level validation

Patterns visible across services:

• <field> is required
• mode must be one of: ...
• unsupported privacy setting
• rules must be ...
• reaction must contain at least one valid reaction item
• media must be an object

Transport-level errors

TdlibBaseClient.tg_call() returns:

• {"ok": false, "result": null, "error": "<string>"}

No stable numeric error enum is enforced in the transport wrapper.

Unsupported command

If the registry does not find a handler, dispatch_command_payload() emits:

• event type: <command>_error
• error text: Unsupported command: <command>

Error model limitations

• errors are string-based, not schema-bound
• some commands return structured partial results plus error
• there is no central error-code catalog in the subsystem

Recommendation for future stabilization

If the team wants a stricter public contract, the next step should be a shared error schema layer with:

• code
• message
• details
• retriable
• source