中亿丰数字前后端接口请求说明书
一、简介
服务器接口设计中最重要的环节之一便是接口请求格式和接口错误码的定义了，通常情况下服务端会定义一些错误码用以指示接口调用者或者用户进行正确的操作。例如接口参数确实、参数非法、无权限访问、用户身份认证信息过期等等类似反馈。
二、请求格式
Page int json:”page”
Size int json”size”
Limit int json:”limit”
Offset int json:”offset”
Sort int json:sort
三、返回格式
1、最简返回示例
Code int json:”code”
Msg string json:”msg”
2、带数据返回示例
Code int json:”code”
Msg string json:”msg”
Data interface{} json:data
Redirect string json:”redirect”
Page int json:”page”
Size int json”size”
Count int json:”count”
四、字段说明
Page：分页码，第几页
Size：分页数量，每页数据条数
Limit: 指定返回记录的数量
Offset：指定返回记录的开始位置
Sort: 排序类型
Code：响应编码，例：0或200成功，401请登录，403无权限，500错误
Count: 数据行总数，针对本层统计多少条记录（行数）
Sum：数据总数，用来汇总该层某一列数据的合计值
Total:数据总数，全部的，完全的，彻底的，一般用于本层和本层以下所有数据总数。
Data：数据，也有用List的，视情况而定
Msg：消息提示语，也有用Message的，视情况而定
Redirect：跳转链接
五、自定义错误码对照表（参考微博开放平台）
1、错误代码声明
| 首位数字 | 两位数字 | 两位数字 |
|---|---|---|
| 1：系统级错误 | 00：模块未定义 | 具体错误代码 |
| 2：服务级错误 | 05：服务模块或类别代码 |
2、系统级错误代码
| 错误代码 | 错误信息 | 详细描述 |
|---|---|---|
| 10001 | System error | 系统错误 |
| 10002 | Service unavailable | 服务暂停 |
| 10003 | Remote service error | 远程服务错误 |
| 10004 | IP limit | IP限制不能请求该资源 |
| 10005 | Permission denied, need a high level appkey | 该资源需要appkey拥有授权 |
| 10006 | Source paramter (appkey) is missing | 缺少source (appkey) 参数 |
| 10007 | Unsupport mediatype (%s) | 不支持的MediaType (%s) |
| 10008 | Param error, see doc for more info | 参数错误，请参考API文档 |
| 10009 | Too many pending tasks, system is busy | 任务过多，系统繁忙 |
| 10010 | Job expired | 任务超时 |
| 10011 | RPC error | RPC错误 |
| 10012 | Illegal request | 非法请求 |
| 10013 | Invalid user | 不合法的用户 |
| 10014 | Insufficient app permissions | 应用的接口访问权限受限 |
| 10016 | Miss required parameter (%s) , see doc for more info | 缺失必选参数 (%s)，请参考API文档 |
| 10017 | Parameter (%s)'s value invalid, expect (%s) , but get (%s) , see doc for more info | 参数值非法，需为 (%s)，实际为 (%s)，请参考API文档 |
| 10018 | Request body length over limit | 请求长度超过限制 |
| 10020 | Request api not found | 接口不存在 |
| 10021 | HTTP method is not suported for this request | 请求的HTTP METHOD不支持，请检查是否选择了正确的POST/GET方式 |
| 10022 | IP requests out of rate limit | IP请求频次超过上限 |
| 10023 | User requests out of rate limit | 用户请求频次超过上限 |
| 10024 | User requests for (%s) out of rate limit | 用户请求特殊接口 (%s) 频次超过上限 |
3、服务级错误代码
| 错误代码 | 错误信息 | 详细描述 |
|---|---|---|
| 20001 | IDs is null | IDs参数为空 |
| 20002 | Uid parameter is null | Uid参数为空 |
| 20003 | User does not exists | 用户不存在 |
| 20005 | Unsupported image type, only suport JPG, GIF, PNG | 不支持的图片类型，仅仅支持JPG、GIF、PNG |
| 20006 | Image size too large | 图片太大 |
| 20007 | Does multipart has image | 请确保使用multpart上传图片 |
| 20008 | Content is null | 内容为空 |
| 20009 | IDs is too many | IDs参数太长了 |
| 20012 | Text too long, please input text less than 140 characters | 输入文字太长，请确认不超过140个字符 |
| 20013 | Text too long, please input text less than 300 characters | 输入文字太长，请确认不超过300个字符 |
| 20014 | Param is error, please try again | 安全检查参数有误，请再调用一次 |
| 20015 | Account or ip or app is illgal, can not continue | 账号、IP或应用非法，暂时无法完成此操作 |
| 20016 | Out of limit | 发布内容过于频繁 |
| 20017 | Repeat content | 提交相似的信息 |
| 20018 | Contain illegal website | 包含非法网址 |
| 20019 | Repeat conetnt | 提交相同的信息 |
| 20020 | Contain advertising | 包含广告信息 |
| 20021 | Content is illegal | 包含非法内容 |
| 20022 | Your ip's behave in a comic boisterous or unruly manner | 此IP地址上的行为异常 |
| 20031 | Test and verify | 需要验证码 |
| 20032 | Update success, while server slow now, please wait 1-2 minutes | 发布成功，目前服务器可能会有延迟，请耐心等待1-2分钟 |
| 20101 | ||
| 20201 | ||
| - | - | - |
| 20301 | ||
| - | - | - |
| 20401 | Domain not exist | 域名不存在 |
| 20402 | Wrong verifier | Verifier错误 |
| - | - | - |
| 20501 | Source_user or target_user does not exists | 参数source_user或者target_user的用户不存在 |
| 20502 | Please input right target user id or screen_name | 必须输入目标用户id或者screen_name |
| 20503 | ||
| 20504 | ||
| 20505 | ||
| 20506 | ||
| 20507 | Verification code is needed | 需要输入验证码 |
| - | - | - |
| 20601 | List name too long, please input text less than 10 characters | 列表名太长，请确保输入的文本不超过10个字符 |
| 20602 | List description too long, please input text less than 70 characters | 列表描叙太长，请确保输入的文本不超过70个字符 |
| 20603 | List does not exists | 列表不存在 |
| 20604 | Only the owner has the authority | 不是列表的所属者 |
| 20605 | Illegal list name or list description | 列表名或描叙不合法 |
| 20606 | Object already exists | 记录已存在 |
| 20607 | DB error, please contact the administator | 数据库错误，请联系系统管理员 |
| 20608 | List name duplicate | 列表名冲突 |
| 20610 | Does not support private list | 目前不支持私有分组 |
| 20611 | Create list error | 创建列表失败 |
| 20612 | Only support private list | 目前只支持私有分组 |
| 20613 | You hava subscriber too many lists | 订阅列表达到上限 |
| 20614 | Too many lists, see doc for more info | 创建列表达到上限，请参考API文档 |
| 20615 | Too many members, see doc for more info | 列表成员上限，请参考API文档 |
| - | - | - |
| 20701 | Repeated tag text | 不能提交相同的收藏标签 |
| 20702 | Tags is too many | 最多两个收藏标签 |
| 20703 | Illegal tag name | 收藏标签名不合法 |
| - | - | - |
| 20801 | Trend_name is null | 参数trend_name是空值 |
| 20802 | Trend_id is null | 参数trend_id是空值 |
| - | - | - |
| 20901 | ||
| - | - | - |
| 21001 | Tags parameter is null | 标签参数为空 |
| 21002 | Tags name too long | 标签名太长，请确保每个标签名不超过14个字符 |
| - | - | - |
| 21101 | Domain parameter is error | 参数domain错误 |
| 21102 | The phone number has been used | 该手机号已经被使用 |
| 21103 | The account has bean bind phone | 该用户已经绑定手机 |
| 21104 | Wrong verifier | Verifier错误 |
| - | - | - |
| 21301 | Auth faild | 认证失败 |
| 21302 | Username or password error | 用户名或密码不正确 |
| 21303 | Username and pwd auth out of rate limit | 用户名密码认证超过请求限制 |
| 21304 | Version rejected | 版本号错误 |
| 21305 | Parameter absent | 缺少必要的参数 |
| 21306 | Parameter rejected | OAuth参数被拒绝 |
| 21307 | Timestamp refused | 时间戳不正确 |
| 21308 | Nonce used | 参数nonce已经被使用 |
| 21309 | Signature method rejected | 签名算法不支持 |
| 21310 | Signature invalid | 签名值不合法 |
| 21311 | Consumer key unknown | 参数consumer_key不存在 |
| 21312 | Consumer key refused | 参数consumer_key不合法 |
| 21313 | Miss consumer key | 参数consumer_key缺失 |
| 21314 | Token used | Token已经被使用 |
| 21315 | Token expired | Token已经过期 |
| 21316 | Token revoked | Token不合法 |
| 21317 | Token rejected | Token不合法 |
| 21318 | Verifier fail | Pin码认证失败 |
| 21319 | Accessor was revoked | 授权关系已经被解除 |
| 21320 | OAuth2 must use https | 使用OAuth2必须使用https |
| 21321 | Applications over the unaudited use restrictions | 未审核的应用使用人数超过限制 |
| 21327 | Expired token | token过期 |
| 21335 | Request uid's value must be the current user | uid参数仅允许传入当前授权用户uid |
| - | - | - |
| 21501 | Urls is null | 参数urls是空的 |
| 21502 | Urls is too many | 参数urls太多了 |
| 21503 | IP is null | IP是空值 |
| 21504 | Url is null | 参数url是空值 |
| - | - | - |
| 21601 | Manage notice error, need auth | 需要系统管理员的权限 |
| 21602 | Contains forbid world | 含有敏感词 |
| 21603 | Applications send notice over the restrictions | 通知发送达到限制 |
| - | - | - |
| 21701 | Manage remind error, need auth | 提醒失败，需要权限 |
| 21702 | Invalid category | 无效分类 |
| 21703 | Invalid status | 无效状态码 |
| - | - | - |
| 21901 | Geo code input error | 地理信息输入错误 |
六、通用状态码总体分类
| 类别 | 说明 | 描述 |
|---|---|---|
| 1xx | 信息 | 通信传输协议信息 |
| 2xx | 成功 | 表示客户端的请求已成功接受 |
| 3xx | 重定向 | 表示客户端必须执行一些其他操作才能完成其请求 |
| 4xx | 客户端错误 | 此类错误状态码指定客户端 |
| 5xx | 服务器错误 | 服务器负责这些错误状态码 |
七、通用状态码列表
| 代码 | 中文 |
|---|---|
| 0 | 一切都好，一切都很成功。 |
| 100 | （继续）现在一切正常，继续。 |
| 101 | （切换协议）有消息，例如升级请求、正在将事物更改为不同的协议。 |
| 102 | 正在发生但尚未完成。 |
| 103 | （预提示）让你预加载资源，这有助于改进核心网页指标的最大内容绘制指标。 |
| 200 | （成功）服务器已成功处理了请求。 通常，这表示服务器提供了请求的网页。 |
| 201 | （已创建）与 200 类似，但衡量成功的标准是创建了新资源。 |
| 202 | （已接受）已接受处理请求，但尚未完成。它甚至可能还没有开始。 |
| 203 | （非授权信息）服务器已成功处理了请求，但返回的信息可能来自另一来源。 |
| 204 | （无内容 ）服务器成功处理了请求，但没有返回任何内容。 |
| 205 | （重置内容）将文档重置为原始状态，服务器成功处理了请求，但没有返回任何内容。例如，清除表单。 |
| 206 | （部分内容）只发送了部分内容，服务器成功处理了部分 GET 请求。 |
| 207 | （多状态 ）有更多的响应代码，可能是 2xx、3xx、4xx 或 5xx。 |
| 208 | （已经报告）客户端告诉服务器之前提到的相同资源。 |
| 218 | （良好）非官方，Apache 使用 |
| 226 | （IM 使用）这允许服务器向客户端发送资源的更改（差异）。 |
| 300 | （多项选择）有不止一种可能的响应，你可能必须选择其中之一。 |
| 301 | （永久跳转）旧资源现在重定向到新的资源上。 |
| 302 | （临时跳转 ）旧资源现在临时重定向到新资源。 |
| 303 | （查看其他）这是另一个重定向，表明资源可能在其他地方找到。 |
| 304 | （无修改）表示页面没有被修改。通常用于缓存。 |
| 305 | （使用代理）请求的资源仅在你使用代理时可用。 |
| 306 | （切换代理）你的下一个请求应使用指定的代理。此代码不再使用。 |
| 307 | （临时重定向）具有与 302 重定向相同的功能，但你不能在 POST 和 GET 之间切换。 |
| 307 | （HSTS 机制）强制客户端在发出请求时使用 HTTPS 而不是 HTTP。 |
| 308 | （永久重定向）具有与 301 重定向相同的功能，但你不能在 POST 和 GET 之间切换。 |
| 400 | （请求错误）客户端请求有问题。它可能格式不正确、无效或太大、或现在服务器无法理解请求。 |
| 401 | （未授权）请求要求身份验证。 对于需要登录的网页，服务器可能返回此响应。 |
| 402 | （支付请求）这没有官方用途，它是为未来的某种数字支付系统保留的。一些商家出于自身原因使用此功能，例如 Shopify在商店未支付费用时使用此功能，而 Stripe 将其用于潜在的欺诈性付款。 |
| 403 | （阻止访问）客户端已知但没有访问权限。 |
| 404 | （未找到）未找到请求的资源。 |
| 405 | （方法不被允许）不支持使用的请求方法，例如，表单需要使用 POST 但使用 GET 代替。 |
| 406 | （不被接受）客户端请求的接受头不能被服务器完成。 |
| 407 | （代理身份验证）需要通过代理进行身份验证。 |
| 408 | （请求超时）服务器已超时、或决定关闭连接。 |
| 409 | （冲突）请求与服务器状态冲突。 |
| 410 | （丢失）类似于未找到请求的 404，但这也表示它不会再次可用。 |
| 411 | （字段长度请求）请求没有包含内容长度字段。 |
| 412 | （前提条件失败）客户端对服务器的请求不满足设置条件。 |
| 413 | （超出限制）请求大小超出服务器的限制。 |
| 414 | （URI 过长）请求的 URI 超出服务器限制。 |
| 415 | （不支持该格式）服务器不支持请求的格式。 |
| 416 | （超出范围）客户端请求服务器无法提供的文件部分。例如，它请求文件实际结束位置之外的文件部分。 |
| 417 | （预期失败）服务器无法满足 “Expect” 请求标头中指示的预期。 |
| 419 | （页面过期）非官方，Laravel 框架使用。 |
| 420 | （方法失败）非官方，Spring Framework 使用。 |
| 421 | （被误导的请求）请求发送到的服务器无法响应。 |
| 422 | （实体无法处理）请求中存在语义错误。 |
| 423 | （锁定）请求的资源被锁定。 |
| 424 | （依赖失败）发生此故障是因为它需要另一个同样失败的请求。 |
| 425 | （过早请求）服务器此时不愿意处理请求，因为请求很可能稍后会再次出现。 |
| 426 | （需要升级）服务器拒绝请求，直到客户端使用更新的协议。 “升级” 标题中会指出需要升级的内容。 |
| 428 | （需要先决条件）服务器要求请求是有条件的。 |
| 429 | （请求过多）这是一种保护服务器的速率限制形式，因为客户端向服务器发送的请求太快了。 |
| 430 | （请求标头字段太大）非官方，Shopify 使用。 |
| 431 | 请求标头字段太大 – 服务器不会处理请求，因为标头字段太大。 |
| 440 | （登录超时）非官方，IIS 使用。 |
| 444 | （无响应）非官方，nginx 使用。 |
| 449 | （重试）非官方，IIS 使用。 |
| 450 | （被 Windows 家长控制阻止）非官方，Microsoft 使用。 |
| 451 | （因法律原因不可用）由于某种法律原因而被阻止。由于隐私或许可，你有时会在国家级屏蔽中看到它，例如，屏蔽新闻或视频。 |
| 451 | （重定向）非官方，IIS 使用。 |
| 460 | 非官方，AWS Elastic Load Balancer 使用。 |
| 463 | 非官方，AWS Elastic Load Balancer 使用。 |
| 494 | （请求标头太大）非官方，nginx 使用。 |
| 495 | （SSL 证书错误）非官方，nginx 使用。 |
| 496 | （需要SSL 证书）非官方，nginx 使用。 |
| 497 | （HTTP 请求发送到 HTTPS 端口）非官方，nginx 使用。 |
| 498 | （非法 Token）非官方，Esri 使用。 |
| 499 | （客户端关闭请求）非官方，nginx 使用。 |
| 499 | （需要 Token）非官方，Esri 使用。 |
| 500 | （内部服务器错误）服务器遇到某种问题、并且没有更好或更具体的错误代码。 |
| 501 | （无法实现）服务器不支持请求方法。 |
| 502 | （网关错误）服务器处于请求中间状态。但是它从它路由到的服务器收到了错误的响应。 |
| 503 | （暂停服务）服务器因维护而过载或停机，现在无法处理请求。它可能很快就会恢复。 |
| 504 | （网关超时）服务器处于请求中间状态。但是没有收到来自它路由到的服务器的及时响应。 |
| 505 | （HTTP 版本不支持）服务器不支持请求中的 HTTP 协议版本。 |
| 506 | （变体协商 ) 当服务器有多个变体时，允许客户端获得资源的最佳变体。 |
| 507 | （存储空间不足）服务器无法存储完成请求所需存储的内容。 |
| 508 | （检测到环路）服务器在尝试处理请求时发现无限循环。 |
| 509 | （超出带宽限制）非官方，Apache 和 cPanel 使用。 |
| 510 | （未扩展）在服务器完成请求之前，需要对请求进行更多扩展。 |
| 511 | （需要网络身份验证）客户端需要在服务器允许访问之前，进行身份验证。 |
| 520 | （Web 服务器返回未知错误）非官方，Cloudflare 使用。 |
| 521 | （Web服务器已关闭）非官方，Cloudflare 使用。 |
| 522 | （链接超时）非官方，Cloudflare 使用。 |
| 523 | （来源失效）非官方，Cloudflare 使用。 |
| 524 | （发生超时）非官方，Cloudflare 使用。 |
| 525 | （SSL链接失败）非官方，Cloudflare 使用。 |
| 526 | （SSL 证书无效）非官方，Cloudflare 使用。 |
| 527 | （Railgun 错误）非官方，Cloudflare 使用。 |
| 529 | （网站超载）非官方，Qualys 使用。 |
| 530 | 非官方，Cloudflare 使用。 |
| 530 | （站点被冻结）非官方，Pantheon 使用。 |
| 561 | （未授权）非官方，AWS Elastic Load Balancer 使用。 |
| 598 | （（非正式）网络读取超时错误）非官方，某些 HTTP 代理使用。 |
作者：扶云星程
浙公网安备 33010602011771号