差别
这里会显示出您选择的修订版和当前版本之间的差别。
两侧同时换到之前的修订记录 前一修订版 后一修订版 | 前一修订版 | ||
im:other:errorcode:restapi [2019/06/14 10:13] jk [索引 错误结果说明] |
im:other:errorcode:restapi [2022/06/14 10:04] (当前版本) jennifer.zeng |
||
---|---|---|---|
行 1: | 行 1: | ||
- | ====== 服务器端 REST API 常见错误码 ====== | + | ===== 常见错误代码 ===== |
- | ---- | + | ''该文档已不再维护,请看新版 3.X 文档。新版文档见:[[ccim:rest:errorcode|常见错误代码]]。'' |
- | ===== HTTP 返回结果示例 ===== | + | |
- | REST 接口调用后,HTTP 会状态码以及标准 JSON 格式的返回结果。可根据返回数据中的 error 字段判断具体错误。 | + | |
- | * HTTP 状态返回代码 200(成功) | + | |
- | * HTTP 状态返回代码 4xx(请求错误)这些状态代码表示请求可能出错,妨碍了服务器的处理。 | + | |
- | * HTTP 状态返回代码 5xx(服务器错误)这些状态代码表示服务器在尝试处理请求时发生内部错误。 | + | |
- | ===返回示例 === | + | ------- |
- | {{:start:450errorcode:response_icon.jpg?nolink|REST API返回错误示例}} | + | 本文介绍 REST 接口调用后的返回结果响应码。可根据返回数据中的 error 字段判断具体错误。 |
- | 建议对 APP 自己的服务器端调用的环信 REST API 结果做容错处理。比如要 catch 接口调用返回的异常,对于 timeout 这样的错误应该做重试。对于系统级别错误或重试后仍旧出错,应该记录到系统日志,并及时报警提示运维人员做补救措施,如人工补发。 | + | * 响应码:200(成功) |
+ | * 响应码:4xx(请求错误)。这些状态代码表示请求可能出错,妨碍了服务器的处理。 | ||
+ | * 响应码:5xx(服务器错误)。这些状态代码表示服务器在尝试处理请求时发生内部错误。 | ||
- | ===== 索引 错误状态码===== | + | === 返回示例 === |
- | ^HTTP 返回码(Status Code) ^说明(Description)^ | + | {{https://docs-im.easemob.com/_media/start/450errorcode/response_icon.jpg|REST API返回错误示例}} |
- | |400|(错误请求)服务器不理解请求的语法。| | + | |
- | |401|(未授权)请求要求身份验证。对于需要token的接口,服务器可能返回此响应。| | + | |
- | |403|(禁止)服务器拒绝请求。对于群组/聊天室服务,表示本次调用不符合群组/聊天室操作的正确逻辑,例如调用添加成员接口,添加已经在群组里的用户,或者移除聊天室中不存在的成员等操作。| | + | |
- | |404|(未找到)服务器找不到请求的接口。| | + | |
- | |408|(请求超时)服务器等候请求时发生超时。| | + | |
- | |413|(请求体过大)请求体超过了5kb,拆成更小的请求体重试即可。| | + | |
- | |415|请求体的类型不支持。| | + | |
- | |429|(服务不可用)请求接口超过调用频率限制,即接口被限流。或超过社区版限制,如有需要可联系商务。| | + | |
- | |500|(服务器内部错误)服务器遇到错误,无法完成请求。| | + | |
- | |501|(尚未实施)服务器不具备完成请求的功能。例如,服务器无法识别请求方法时可能会返回此代码。| | + | |
- | |502|(错误网关)服务器作为网关或代理,从上游服务器收到无效响应。| | + | |
- | |503|(服务器超时)Service Unavailable。| | + | |
- | |504|(网关超时)服务器作为网关或代理,但是没有及时从上游服务器收到请求。| | + | |
- | =====索引 错误结果说明 ===== | + | 建议对 app 自己的服务器端调用的 REST API 结果做容错处理,比如: |
- | ^HTTP Status Code ^Error ^Error Description ^可能原因^ | + | * catch 接口调用返回的异常 timeout 可以尝试重新调用。 |
- | |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/server/ready/user|文档]]| | + | |
- | |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下创建的群组或聊天室数量以达到限制。| | + | |
- | |403|||没有开通音视频增值服务调用接口失败| | + | |
- | |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/other/errorcode/restastrict|接口限流标准]]| | + | |
- | |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发送了请求| | + | |
+ | ===== 索引 错误状态码 ===== | ||
- | ---- | + | ^HTTP 返回码(Status Code)^说明(Description) ^ |
- | <WRAP group> | + | | 400 | (错误请求)服务器不理解请求的语法。 | |
- | <WRAP half column> | + | | 401 | (未授权)请求要求身份验证。对于需要 token 的接口,服务器可能返回此响应。 | |
- | 上一章:[[im:extensions:live:intro|扩展功能]] | + | | 403 | (禁止)服务器拒绝请求。对于群组/聊天室服务,表示本次调用不符合群组/聊天室操作的正确逻辑,例如调用添加成员接口,添加已经在群组里的用户,或者移除聊天室中不存在的成员等操作。 | |
- | </WRAP> | + | | 404 | (未找到)服务器找不到请求的接口。 | |
+ | | 405 | (请求方式错误)请按照环信官网接口说明,正确的使用接口 GET,POST 等请求方式。 | | ||
+ | | 408 | (请求超时)服务器等候请求时发生超时。 | | ||
+ | | 413 | (请求体过大)请求体超过了 5 kb,拆成更小的请求体重试即可。 | | ||
+ | | 415 | 请求体的类型不支持。 | | ||
+ | | 429 | (服务不可用)请求接口超过调用频率限制,即接口被限流。或超过社区版限制,如有需要可联系商务。 | | ||
+ | | 500 | (服务器内部错误)服务器遇到错误,无法完成请求。 | | ||
+ | | 501 | (尚未实施)服务器不具备完成请求的功能。例如,服务器无法识别请求方法时可能会返回此代码。 | | ||
+ | | 502 | (错误网关)服务器作为网关或代理,从上游服务器收到无效响应。 | | ||
+ | | 503 | (服务器超时)Service Unavailable。 | | ||
+ | | 504 | (网关超时)服务器作为网关或代理,但是没有及时从上游服务器收到请求。 | | ||
- | <WRAP half column> | + | ===== 索引 错误结果说明 ===== |
- | 下一页:[[im:other:errorcode:android|Android API 常见错误码]] | + | |
- | </WRAP> | + | ^HTTP Status Code^Error ^Error Description ^可能原因 ^ |
- | </WRAP> | + | | 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 is not legal” | 注册使用的 username 不合法,username(Chat ID) 规则见 [[ccim:rest:accountsystem|用户体系集成]] | | ||
+ | | 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 的描述为 App Key 使用了授权注册,需要 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 | forbidden_op | “can not join this group, reason:user %s has joined too many groups/chatroom!” | 用户加入群组或聊天室数超过了限制。 | | ||
+ | | 403 | forbidden_op | “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 | service_resource_not_found | “Service resource not found” | 要删除的 username 不存在,若用户列表存在该 username,则可使用 user 的 uuid 代替 username 删除。 | | ||
+ | | 404 | storage_object_not_found | “Failed to find chat message history download url for appkey: hx#hxdemo2, time: 2018020912” | 对应的时间没有聊天记录,如确定有聊天记录,请提交工单反馈 Agora Chat 技术支持团队确认。 | | ||
+ | | 413 | Request Entity Too Large | “Request Entity Too Large” | 请求体过大,如上传文件时文件过大;或发送消息时消息体过大,请求体如果超过 5kb 会导致 413 错误,需要拆成几个更小的请求体重试,同时用户消息+扩展字段的长度在 4k 字节以内。 | | ||
+ | | 415 | web_application | “Unsupported Media Type” | 请求体的类型不支持,请检查 header 是否添加 ”Content-Type”:“application/json”,body 是否符合标准的 JSON 格式,再确认 header 中是否还有非接口需要的参数,可以舍去。 | | ||
+ | | 429 | resource_limited | “You have exceeded the limit of the Free edition. Please upgrade to higher edition.” | 说明触发了免费版限制,请联系环信客户经理咨询。 | | ||
+ | | 429 | reach_limit | “This request has reached api limit” | 超过接口每秒调用次数,加大调用间隔或者联系商务调整限流大小,见 [[ccim:limitation|限制条件]]。 | | ||
+ | | 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 发送了请求。 | |