====== 服务器端 REST API 常见错误码 ====== 更新时间：2020-12-31 新版文档见：[[ccim:rest:errorcode|常见错误代码]]。 ---- REST 接口调用成功时返回 HTTP 状态码为 200，返回数据结果为标准 JSON 格式。如调用错误会返回除 200 之外的其他 HTTP 状态码，返回数据结果也为标准 JSON 格式，可根据返回数据中的 error 字段判断具体错误。 例如： {{:start:450errorcode:response_icon.jpg?nolink|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 ^可能原因^ |400|invalid_grant|invalid username or password|用户名或者密码输入错误| |400|invalid_grant|"client_id does not match" |"client_id does not match"是client_id传入不正确，"client_secret does not match"是client_secret传入不正确，client_id以及client_secret在管理后台对应的应用详情中查看 | |400|json_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格式，服务器无法正确解析| |400|illegal_argument|“Entity user requires a property named username” |创建用户请求体未提供“username”| |400|illegal_argument|“password or pin must provided” |创建用户请求体未提供“password”或提供了password但是值为空字符| |400|illegal_argument|“newpassword is required” |修改用户密码的请求体没提供newpassword属性| |400|illegal_argument|"oldPassword is required"|这个是因为没有加管理员token的header导致，需要header加上管理员token的参数即可| |400|illegal_argument|“group member username1 doesn’t exist” |批量添加群组时预加入群组的新成员username不存在| |400|illegal_argument|"this is an invalid request." |请求无效，请检查调用接口的url、header、body，是否符合所调用接口的要求，可以使用curl命令进行测试| |400|illegal_argument|"from can't be empty" |from表示消息发送者，无此字段Server会默认设置为"from":"admin"，有from字段但值为空字符串("")时请求失败，返回400| |400|illegal_argument|"target_type can only be 'users' or 'chatgroups' or 'chatrooms'" |target_type只能为'users' or 'chatgroups' or 'chatrooms'，为其他字符串时请求失败，返回400 | |400|illegal_argument|"username [hxtest1@easemob.com] is not legal"|注册使用的username不合法，username(环信ID)规则见文档：http://docs.easemob.com/im/100serverintegration/20users| |400|illegal_argument|"This chatmessage request is not supported"|可能是传入的时间格式不正确，正确的格式是：YYYYMMDDHH，如要获取2018年02月09日12点到13点的聊天记录，这样设置：2018020912| |400|illegal_argument|"illegal arguments: appkey: easemob-demo#chatdemoui, time: 2018020918, maybe chat message history is expired or unstored"|对应时间的聊天记录还未生成或已过期，目前聊天记录免费保存3天。| |400|invalid_parameter|"some of [groupid] are not valid fields"|修改群信息目前只支持修改“群名称”、“群描述”、“群最大人数”，这个error是修改的参数不支持，如修改groupid| |400|required_property_not_found|"Entity user requires a property named username"|这个是被重置密码的username不存在导致| |400|duplicate_unique_property_exists|"Application null Entity user requires that property named username be unique, value of hxtest1 exists" |注册的username已存在，返回400；注：如果是批量注册，若一次调用返回一个ID已存在，则此次调用注册的其他不存在的ID不会注册，需将已存在的ID从数组中移除重新调用注册| |401|unauthorized|“registration is not open, please contact the app admin”|返回401是未授权，error_description的描述为appkey使用了授权注册，需要header加上管理员token，才有权限注册用户；若加上token返回401，则token可能失效，建议重取重试；| |401|unauthorized|“Unable to authenticate due to expired access token” |token过期或未传token | |401|auth_bad_access_token|“Unable to authenticate due to corrupt access token” |发送请求时使用的token错误。注意：不是token过期| |401|auth_bad_access_token|“Unable to authenticate” |无效token，符合token的格式，但是该token不是接受请求的系统生成的，系统无法识别该token| |403|forbidden_op|"can not join this group, reason:user: hxtest1 already in group: 40659491815425\n"|群组加人返回403说明用户已经在群内。| |403|forbidden_op|"users [hxtest100] are not members of this group!"|群组减人返回403说明被踢的用户本身就不在群内。| |403|forbidden_op|"user: username1 doesn't exist in group: 40659491815425"|转让群组返回403，error_description说明用户被转让的用户不是群成员，无法转让。| |403|forbidden_op|"new owner and old owner are the same"|转让群组返回403，error_description说明被转让的用户已经是群主。| |403|forbidden_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下创建的群组或聊天室数量以达到限制。| |404|organization_application_not_found|"Could not find application for hx/hxdeo2 from URI: hx/hxdeo2/token"|hx/hxdeo2这个设置不正确或不存在，或baseurl集群设置错误（只针对vip集群的appkey），正确的是orgname/appname，即appkey的"#"换成"/"；| |404|service_resource_not_found|“Service resource not found” |URL指定的资源不存在，如用户相关接口是用户不存在，群组相关接口是群组不存在，聊天室相关接口是聊天室不存在 | |404|service_resource_not_found|“Service resource not found” |获取的username不存在，若用户列表存在该username，则是因为存在脏数据，可以使用uuid代替username将该ID删除，再使用该username重新创建；| |404|||删除的username不存在，若用户列表存在该username，则可使用user的uuid代替username删除；| |404|storage_object_not_found|"Failed to find chat message history download url for appkey: hx#hxdemo2, time: 2018020912"|对应的时间没有聊天记录，如确定有聊天记录，请提交工单反馈环信技术支持团队确认| |413|Request Entity Too Large|“Request Entity Too Large” |请求体过大，如上传文件时文件过大；或发送消息时消息体过大，请求体如果超过5kb会导致413错误，需要拆成几个更小的请求体重试，同时用户消息+扩展字段的长度在40k字节以内 | |415|web_application|"Unsupported Media Type" |请求体的类型不支持，请检查header是否添加"Content-Type":"application/json"，body是否符合标准的JSON格式，再确认header中是否还有非接口需要的参数，可以舍去| |429|resource_limited|"You have exceeded the limit of the community edition. Please upgrade to the enterprise edition." |说明触发了社区版限制，社区版限制介绍：http://www.easemob.com/pricing/im，如您已开通企业版，请联系环信商务处理| |429|reach_limit|"This request has reached api limit" |超过接口每秒调用次数，加大调用间隔或者联系商务调整限流大小，接口限流标准见：http://docs.easemob.com/im/450errorcode/45restastrict| |500|no_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操作| |500|unsupported_service_operation|“Service operation not supported” |请求方式不被发送请求的URL支持| |500|web_application|“javax.ws.rs.WebApplicationException” |错误的请求，给一个未提供的API发送了请求| ---- 上一章节：[[im:400webimintegration|Web IM集成]] 下一页：[[start:450errorcode:20androiderrorcode|Android API常见错误码]]