上报客户端错误

记录客户端错误，便于在后台汇总和排查。通常由 SDK 自动提交，宿主无需重复实现上报。

POST /app/sdk/client-errors

调用方： SDK 客户端　·　认证： IM Token

请求头：Authorization: Bearer <IM Token>。先通过宿主后端获取 Token，再交给 SDK 使用。

请求参数

JSON Body

参数	类型	必填	说明
event_id	string	是	本次错误事件的小写 UUID v4，重试时使用相同值。
user_id	string	是	当前用户的外部 user_id，1–64 字符，必须与 IM Token 身份一致。
username	string | null	是	当前账号，最长 64 字符；没有时为 null。
device_id	string	是	当前安装设备的稳定标识，1–128 位字母、数字、点、下划线、冒号或连字符。同一台设备持续使用同一个值。
platform	string	是	客户端平台：android、ios、harmony。
severity	string	是	normal 普通、serious 严重、fatal 致命。
error_code	string	是	稳定的错误分类，最长 128 字符；由小写字母、数字组成，可用单个点、下划线、连字符分隔各段。
message	string	是	错误说明，非空，最长 4096 字符。
stack_trace	string | null	是	错误堆栈，最长 32768 字符；没有时为 null。
operation	string	是	错误发生时的操作，非空，最长 128 字符。
build_id	string | null	是	客户端构建或版本标识，最长 128 字符。
conversation_id	string | null	是	关联会话 ID，最长 512 字符；没有时为 null。
message_id	string | null	是	关联消息 ID，最长 128 字符；没有时为 null。
trace_id	string | null	是	关联追踪 ID，小写 UUID v4；没有时为 null。
recovered	boolean	是	当前是否已经从此错误中恢复。
context	object	是	至少包含一个键的上下文对象，不能传数组；键按诊断场景定义。

请求示例

curl 'https://example.com/app/sdk/client-errors' \
  -H "Authorization: Bearer $POPOIM_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"event_id":"a6235b68-c416-4b12-932e-38a6aa7cb58e","user_id":"chenyue","username":"chenyue","device_id":"office-ios-01","platform":"ios","severity":"normal","error_code":"network.unavailable","message":"network.unavailable","stack_trace":null,"operation":"messages.refresh","build_id":"1.0.0","conversation_id":null,"message_id":null,"trace_id":null,"recovered":true,"context":{"stage":"network.recovery"}}'

使用说明

• 必须完整提交上表 16 项；允许为空的字段也要保留字段名，值用 null。
• 同一分钟内的同类错误可能合并，使用返回的 event_id 记录服务器结果。
• 错误说明、堆栈和上下文不要包含聊天正文、密码、验证码、Token 或完整请求头。

返回参数

成功响应的最外层字段如下。下面所有业务字段都位于 data 中。

字段	类型	说明
code	integer	0 表示成功；非 0 时查看 msg，不把 data 当成功结果使用。
msg	string	成功通常为 ok，失败时为错误说明。
data	object	本次请求的业务结果，字段见下表。

data 字段

字段	类型	说明
event_id	string	服务器保存或合并后的错误记录 ID，可能与提交的 ID 不同。
occurrence_count	integer	此条错误记录合并后的累计出现次数。

返回示例

示例展示字段结构；ID、时间和资料仅作说明，请使用实际回包。

{
  "code": 0,
  "msg": "ok",
  "data": {
    "event_id": "a6235b68-c416-4b12-932e-38a6aa7cb58e",
    "occurrence_count": 1
  }
}

错误处理

先检查 HTTP 状态，再检查 code。业务失败可能仍为 HTTP 200；非 0 的 code 都不能当成功。完整错误码见请求约定。

返回举报与诊断接口列表 · HTTP 请求约定