服务器端 REST API 常见错误码


REST 接口调用成功时返回 HTTP 状态码为 200,返回数据结果为标准 JSON 格式。如调用错误会返回除 200 之外的其他 HTTP 状态码,返回数据结果也为标准 JSON 格式,可根据返回数据中的 error 字段判断具体错误。

例如:

REST API返回错误示例

建议对 APP 自己的服务器端调用的环信 REST API 结果做容错处理。比如要 catch 接口调用返回的异常,对于 timeout 这样的错误应该做重试。对于系统级别错误或重试后仍旧出错,应该记录到系统日志,并及时报警提示运维人员做补救措施,如人工补发。

HTTP 状态返回代码 4xx(请求错误)这些状态代码表示请求可能出错,妨碍了服务器的处理。

HTTP 状态返回代码 5xx(服务器错误)这些状态代码表示服务器在尝试处理请求时发生内部错误。

HTTP 返回码(Status Code) 说明(Description)
400(错误请求)服务器不理解请求的语法。
401(未授权)请求要求身份验证。对于需要token的接口,服务器可能返回此响应。
403(禁止)服务器拒绝请求。对于群组/聊天室服务,表示本次调用不符合群组/聊天室操作的正确逻辑,例如调用添加成员接口,添加已经在群组里的用户,或者移除聊天室中不存在的成员等操作。
404(未找到)服务器找不到请求的接口。
408(请求超时)服务器等候请求时发生超时。
413(请求体过大)请求体超过了5kb,拆成更小的请求体重试即可。
415请求体的类型不支持。
429(服务不可用)请求接口超过调用频率限制,即接口被限流。或超过社区版限制,如有需要可联系商务。
500(服务器内部错误)服务器遇到错误,无法完成请求。
501(尚未实施)服务器不具备完成请求的功能。例如,服务器无法识别请求方法时可能会返回此代码。
502(错误网关)服务器作为网关或代理,从上游服务器收到无效响应。
503(服务不可用)请求接口超过调用频率限制,即接口被限流。
504(网关超时)服务器作为网关或代理,但是没有及时从上游服务器收到请求。
HTTP Status Code Error Error Description 可能原因
400invalid_grantinvalid username or password用户名或者密码输入错误
400invalid_grant“client_id does not match” “client_id does not match”是client_id传入不正确,“client_secret does not match”是client_secret传入不正确,client_id以及client_secret在管理后台对应的应用详情中查看
400json_parse“Unexpected character (‘=’ (code 61)): was expecting a colon to separate field name and value\n at [Source: java.io.BufferedInputStream@170e3f35; line: 1, column: 23]”发送请求时请求体不符合标准的JSON格式,服务器无法正确解析
400illegal_argument“Entity user requires a property named username” 创建用户请求体未提供“username”
400illegal_argument“password or pin must provided” 创建用户请求体未提供“password”或提供了password但是值为空字符
400illegal_argument“newpassword is required” 修改用户密码的请求体没提供newpassword属性
400illegal_argument“oldPassword is required”这个是因为没有加管理员token的header导致,需要header加上管理员token的参数即可
400illegal_argument“group member username1 doesn’t exist” 批量添加群组时预加入群组的新成员username不存在
400illegal_argument“this is an invalid request.” 请求无效,请检查调用接口的url、header、body,是否符合所调用接口的要求,可以使用curl命令进行测试
400illegal_argument“from can't be empty” from表示消息发送者,无此字段Server会默认设置为“from”:“admin”,有from字段但值为空字符串(“”)时请求失败,返回400
400illegal_argument“target_type can only be 'users' or 'chatgroups' or 'chatrooms'” target_type只能为'users' or 'chatgroups' or 'chatrooms',为其他字符串时请求失败,返回400
400illegal_argument“username [hxtest1@easemob.com] is not legal”注册使用的username不合法,username(环信ID)规则见文档:http://docs.easemob.com/im/100serverintegration/20users
400illegal_argument“This chatmessage request is not supported”可能是传入的时间格式不正确,正确的格式是:YYYYMMDDHH,如要获取2018年02月09日12点到13点的聊天记录,这样设置:2018020912
400illegal_argument“illegal arguments: appkey: easemob-demo#chatdemoui, time: 2018020918, maybe chat message history is expired or unstored”对应时间的聊天记录还未生成或已过期,目前聊天记录免费保存3天。
400invalid_parameter“some of [groupid] are not valid fields”修改群信息目前只支持修改“群名称”、“群描述”、“群最大人数”,这个error是修改的参数不支持,如修改groupid
400required_property_not_found“Entity user requires a property named username”这个是被重置密码的username不存在导致
400duplicate_unique_property_exists“Application null Entity user requires that property named username be unique, value of hxtest1 exists” 注册的username已存在,返回400;注:如果是批量注册,若一次调用返回一个ID已存在,则此次调用注册的其他不存在的ID不会注册,需将已存在的ID从数组中移除重新调用注册
401unauthorized“registration is not open, please contact the app admin”返回401是未授权,error_description的描述为appkey使用了授权注册,需要header加上管理员token,才有权限注册用户;若加上token返回401,则token可能失效,建议重取重试;
401unauthorized“Unable to authenticate due to expired access token” token过期或未传token
401auth_bad_access_token“Unable to authenticate due to corrupt access token” 发送请求时使用的token错误。注意:不是token过期
401auth_bad_access_token“Unable to authenticate” 无效token,符合token的格式,但是该token不是接受请求的系统生成的,系统无法识别该token
403forbidden_op“can not join this group, reason:user: hxtest1 already in group: 40659491815425\n”群组加人返回403说明用户已经在群内。
403forbidden_op“users [hxtest100] are not members of this group!”群组减人返回403说明被踢的用户本身就不在群内。
403forbidden_op“user: username1 doesn't exist in group: 40659491815425”转让群组返回403,error_description说明用户被转让的用户不是群成员,无法转让。
403forbidden_op“new owner and old owner are the same”转让群组返回403,error_description说明被转让的用户已经是群主。
403forbidden_op“forbidden operation on group owner!”不能将群主加入黑名单。
403“can not join this group, reason:user %s has joined too many groups/chatroom!”用户加入群组或聊天室数超过了限制。
403“this appKey has create too many groups/chatrooms!”appkey下创建的群组或聊天室数量以达到限制。
404organization_application_not_found“Could not find application for hx/hxdeo2 from URI: hx/hxdeo2/token”hx/hxdeo2这个设置不正确或不存在,或baseurl集群设置错误(只针对vip集群的appkey),正确的是orgname/appname,即appkey的“#“换成”/“;
404service_resource_not_found“Service resource not found” URL指定的资源不存在,如用户相关接口是用户不存在,群组相关接口是群组不存在,聊天室相关接口是聊天室不存在
404service_resource_not_found“Service resource not found” 获取的username不存在,若用户列表存在该username,则是因为存在脏数据,可以使用uuid代替username将该ID删除,再使用该username重新创建;
404删除的username不存在,若用户列表存在该username,则可使用user的uuid代替username删除;
404storage_object_not_found“Failed to find chat message history download url for appkey: hx#hxdemo2, time: 2018020912”对应的时间没有聊天记录,如确定有聊天记录,请提交工单反馈环信技术支持团队确认
413Request Entity Too Large“Request Entity Too Large” 请求体过大,如上传文件时文件过大;或发送消息时消息体过大,请求体如果超过5kb会导致413错误,需要拆成几个更小的请求体重试,同时用户消息+扩展字段的长度在40k字节以内
415web_application“Unsupported Media Type” 请求体的类型不支持,请检查header是否添加”Content-Type”:“application/json”,body是否符合标准的JSON格式,再确认header中是否还有非接口需要的参数,可以舍去
429resource_limited“You have exceeded the limit of the community edition. Please upgrade to the enterprise edition.” 说明触发了社区版限制,社区版限制介绍:http://www.easemob.com/pricing/im,如您已开通企业版,请联系环信商务处理
429reach_limit“This request has reached api limit” 超过接口每秒调用次数,加大调用间隔或者联系商务调整限流大小,接口限流标准见:http://docs.easemob.com/im/450errorcode/45restastrict
500no_full_text_index“Entity ‘user’ with property named ‘username’ is not full text indexed. You cannot use the ‘contains’ operand on this field” username不支持全文索引,不可以对该字段进行contains操作
500unsupported_service_operation“Service operation not supported” 请求方式不被发送请求的URL支持
500web_application“javax.ws.rs.WebApplicationException” 错误的请求,给一个未提供的API发送了请求

上一章节:Web IM集成