错误码明细

本页汇总 open-im-server 在 API 层可见的错误码，按来源分层维护。

通用基础错误码

来源：pkg/common/servererrs/code.go 与 github.com/openimsdk/tools/errs 的通用约定。

errCode	名称	说明
500	ServerInternalError	服务内部错误
1001	ArgsError	参数错误
1002	NoPermissionError	权限不足
1003	DuplicateKeyError	唯一键冲突
1004	RecordNotFoundError	记录不存在
1501	TokenExpiredError	Token 已过期
1502	TokenInvalidError	Token 无效
1503	TokenMalformedError	Token 格式错误
1504	TokenNotValidYetError	Token 未生效
1505	TokenUnknownError	Token 未知错误
1506	TokenKickedError	Token 已被踢下线
1507	TokenNotExistError	Token 不存在

open-im-server 服务错误码

来源：pkg/common/servererrs/code.go。

errCode	名称	说明
1101	UserIDNotFoundError	用户不存在
1102	RegisteredAlreadyError	账号已注册
1201	GroupIDNotFoundError	群组不存在
1202	GroupIDExisted	群组已存在
1203	NotInGroupYetError	不在群内
1204	DismissedAlreadyError	群组已解散
1205	GroupTypeNotSupport	不支持的群类型
1206	GroupRequestHandled	入群申请已处理
1301	CanNotAddYourselfError	不能添加自己
1302	BlockedByPeer	被对方拉黑
1303	NotPeersFriend	非好友关系
1304	RelationshipAlreadyError	关系已存在
1305	FriendRequestHandled	好友申请已处理
1401	MessageHasReadDisable	已读状态不可改
1402	MutedInGroup	成员被禁言
1403	MutedGroup	群处于禁言状态
1404	MsgAlreadyRevoke	消息已撤回
1601	ConnOverMaxNumLimit	连接数超限
1602	ConnArgsErr	连接参数错误
1603	PushMsgErr	推送消息失败
1604	IOSBackgroundPushErr	iOS 后台推送失败
1701	FileUploadedExpiredError	上传已过期

本批接口重点关注错误码

本次补齐的 9 个接口（group/msg/user）联调时，建议优先关注以下错误码：

errCode	名称	常见触发场景
1001	ArgsError	参数缺失、格式错误（如日期格式非法）
1002	NoPermissionError	群角色越权、无访问权限
1004	RecordNotFoundError	消息记录不存在
1201	GroupIDNotFoundError	目标群组不存在
1204	DismissedAlreadyError	重复解散群组
1404	MsgAlreadyRevoke	重复撤回同一条消息
500	ServerInternalError	未归类内部异常

与官方文档关系

• 本页为 open-im-server 增量文档的一部分，补充官方文档未覆盖或不完整的接口说明。
• 官方基础文档入口：https://docs.openim.io/restapi/apis/introduction

处理建议

• errCode = 0：按成功分支读取 data。
• errCode != 0：按失败分支处理，优先展示 errMsg，日志落 errDlt。
• 对重试型调用，建议仅对白名单错误码做重试，避免无意义重放。