状态码与错误码

服务端使用业务错误码（code）表达结果，并与 HTTP 状态码一一对应。当前契约共 43 个错误码，约定如下：0 成功；1xxx 客户端/参数/权限类（除 1008 外不可重试）；2xxx 服务端/依赖类（可重试）；3xxx SDK 本地错误（不来自服务端）。

错误码概览

分类	错误码数量	HTTP 状态	说明
客户端 / 参数 / 权限（`client`）	30	400 / 401 / 403 / 404 / 410 / 429	参数、权限、资源状态类错误；仅 1008 RATE_LIMITED 可重试
Open API 签名与开通（`openapi`）	5	400 / 401 / 403	签名、时间戳、Nonce、服务开通与回调配置类错误
服务端 / 依赖（`server`）	4	500 / 502 / 503	服务端内部与依赖错误，可退避重试
SDK 本地（`sdk`）	4	—	客户端 SDK 本地错误，不出现在服务端响应中

客户端 / 参数 / 权限错误码

错误码	名称	HTTP 状态	可重试	说明	起始版本
`1001`	`INVALID_PARAMETER`	400	否	参数错误	1.0.0
`1002`	`INVALID_TOKEN`	401	否	Token 无效或已过期	1.0.0
`1003`	`FORBIDDEN`	403	否	无权限	1.0.0
`1004`	`USER_NOT_FOUND`	404	否	用户不存在	1.0.0
`1005`	`GROUP_NOT_FOUND`	404	否	群组不存在	1.0.0
`1006`	`NOT_GROUP_MEMBER`	403	否	未加入群组	1.0.0
`1007`	`MESSAGE_TOO_LARGE`	400	否	消息体过大（上限 5KB）	1.0.0
`1008`	`RATE_LIMITED`	429	是	发送过于频繁	1.0.0
`1009`	`GROUP_MUTED`	403	否	你已被禁言	1.0.0
`1010`	`SENSITIVE_WORD`	400	否	内容包含敏感词	1.0.0
`1011`	`BLOCKED`	403	否	已被对方拉黑或你已拉黑对方	1.0.0
`1012`	`CHATROOM_NOT_FOUND`	404	否	聊天室不存在	1.0.0
`1013`	`CHATROOM_CLOSED`	410	否	聊天室已销毁	1.0.0
`1014`	`NOT_CHATROOM_MEMBER`	403	否	未加入聊天室	1.0.0
`1015`	`MEMBERSHIP_LIMIT`	400	否	成员数量超出上限	1.0.0
`1016`	`USER_BANNED`	403	否	账号已被封禁	1.0.0
`1017`	`APP_DISABLED`	403	否	应用已停用	1.0.0
`1022`	`RECALL_EXPIRED`	400	否	超过撤回时限	1.0.0
`1023`	`MESSAGE_ALREADY_RECALLED`	400	否	消息已撤回	1.0.0
`1025`	`QUOTA_EXCEEDED`	429	是	超出配额	1.0.0
`1026`	`MESSAGE_NOT_EXPANDABLE`	400	否	消息不可扩展（发送时未开启可扩展，或会话类型不支持）	1.1.0
`1027`	`EXPANSION_LIMIT_EXCEEDED`	400	否	消息扩展超出限制（单次 20 对 / 单条 300 对 / 键值长度）	1.1.0
`1028`	`REACTION_INVALID`	400	否	回应标识非法（1-16 字符）	1.1.0
`1029`	`REACTION_LIMIT_EXCEEDED`	400	否	单条消息回应种类超出上限（50）	1.1.0
`1030`	`REACTION_USER_LIMIT_EXCEEDED`	400	否	单个回应参与用户超出上限（100）	1.1.0
`1031`	`TAG_LIMIT_EXCEEDED`	400	否	单用户会话标签数超过上限（20）	1.1.0
`1032`	`TAG_NOT_FOUND`	404	否	标签不存在	1.1.0
`1033`	`TAG_CONVERSATION_LIMIT_EXCEEDED`	400	否	标签内会话数超过上限（1000）	1.1.0
`1034`	`CONVERSATION_NOT_FOUND`	404	否	会话不存在（标签内置顶等操作要求会话已在标签内）	1.1.0
`1035`	`MESSAGE_REJECTED_BY_CALLBACK`	403	否	发送前同步回调拒绝该消息（应用服务器返回 action=block，或降级配置为 block）	1.1.0

Open API 签名与开通错误码

错误码	名称	HTTP 状态	可重试	说明	起始版本
`1018`	`INVALID_SIGNATURE`	401	否	签名错误	1.0.0
`1019`	`TIMESTAMP_EXPIRED`	401	否	时间戳超出允许窗口	1.0.0
`1020`	`NONCE_REPLAYED`	401	否	Nonce 重复	1.0.0
`1021`	`SERVICE_NOT_ACTIVATED`	403	否	服务未开通	1.0.0
`1024`	`CALLBACK_INVALID`	400	否	回调配置无效	1.0.0

服务端 / 依赖错误码

错误码	名称	HTTP 状态	可重试	说明	起始版本
`2001`	`INTERNAL_ERROR`	500	是	服务端内部错误	1.0.0
`2002`	`DEPENDENCY_UNAVAILABLE`	503	是	依赖服务不可用	1.0.0
`2003`	`STORAGE_ERROR`	500	是	存储错误	1.0.0
`2004`	`CALLBACK_DELIVERY_FAILED`	502	是	回调投递失败	1.0.0

SDK 本地错误码

错误码	名称	HTTP 状态	可重试	说明	起始版本
`3001`	`SDK_NOT_CONNECTED`	—	是	长连接未就绪	1.0.0
`3002`	`SDK_TIMEOUT`	—	是	请求超时	1.0.0
`3003`	`SDK_NETWORK_ERROR`	—	是	网络错误	1.0.0
`3004`	`SDK_UNSUPPORTED`	—	否	当前平台不支持该能力	1.0.0

HTTP 状态码分布

HTTP 状态	含义	错误码
400	请求错误	`1001`、`1007`、`1010`、`1015`、`1022`、`1023`、`1024`、`1026`、`1027`、`1028`、`1029`、`1030`、`1031`、`1033`
401	未认证（签名/时间戳/Nonce）	`1002`、`1018`、`1019`、`1020`
403	禁止访问（权限/封禁/未开通）	`1003`、`1006`、`1009`、`1011`、`1014`、`1016`、`1017`、`1021`、`1035`
404	资源不存在	`1004`、`1005`、`1012`、`1032`、`1034`
410	资源已关闭/销毁	`1013`
429	请求过多（限频/配额）	`1008`、`1025`
500	服务端内部错误	`2001`、`2003`
502	回调等上游依赖失败	`2004`
503	服务暂不可用	`2002`

重试建议

场景	建议
1008 RATE_LIMITED / 1025 QUOTA_EXCEEDED	按指数退避重试，并降低请求速率；不要立即重试
2001 / 2002 / 2003 / 2004	服务端或依赖暂时不可用，可退避重试；持续失败请携带 `requestId` 联系运维
1018 / 1019 / 1020	签名、时间戳或 Nonce 错误；修正后重新签名，不要原样重试
1017 APP_DISABLED / 1021 SERVICE_NOT_ACTIVATED	应用被禁用或服务未开通；需在控制台处理，重试无效
1xxx 其他	参数/权限/资源状态错误；修正请求后重试
3xxx	SDK 本地错误（如未连接、超时）；按 SDK 文档处理后重试

不要重试不可重试错误

除 1008、1025 与 2xxx 外，其余错误码（尤其 1017、1021、1018-1020）原样重试不会成功；请先修正请求或完成控制台配置。

错误响应示例

HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8

{
  "code": 1018,
  "msg": "invalid signature",
  "requestId": "req_7f3a9c"
}

状态码与错误码

错误码概览​

客户端 / 参数 / 权限错误码​

Open API 签名与开通错误码​

服务端 / 依赖错误码​

SDK 本地错误码​

HTTP 状态码分布​

重试建议​

错误响应示例​

相关说明​

错误码概览

客户端 / 参数 / 权限错误码

Open API 签名与开通错误码

服务端 / 依赖错误码

SDK 本地错误码

HTTP 状态码分布

重试建议

错误响应示例

相关说明