一、简介

服务器接口设计中最重要的环节之一便是接口请求格式和接口错误码的定义了，通常情况下服务端会定义一些错误码用以指示接口调用者或者用户进行正确的操作。例如接口参数确实、参数非法、无权限访问、用户身份认证信息过期等等类似反馈。

二、请求格式

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 代理使用。

作者：扶云星程

中亿丰数字前后端接口请求说明书相关推荐

（凯思奥2020-03月）问题记录3，GUI问题记录3 4，国际化异常，微信平台接入 = 数据库修改 + 自动化填充 + 前后端接口修正 + 联调测试问题 + 微信与数字账号绑定 + 思考+部署
问题记录3: 1. UserPage: 未登录状态(报解构异常),或直接登出再登录,没有获取用户数据. 2.WorkContentPage gui相关(大片红字报错)(国际化message类型问题) ...
前后端不分离到分离演变,优势,前后端接口联调,排错
前后端分离,不分离简介前言前后端分离已成为互联网项目开发的业界标准使用方式,通过nginx+tomcat的方式(也可以中间加一个nodejs)有效的进行解耦,并且前后端分离会为以后的大型分布式架构 ...
公司项目里如何进行前后端接口联调
最近我的朋友Jack进入一家新的公司,正好公司项目采用的是前后端分离架构,技术栈是Jack非常熟悉的vue全家桶,后端用的是Java语言. 在前后端开发人员碰面之后,协商确定好了前端需要的数据接口(扯 ...
获取后端接口请求中的参数(@PathVariable，@RequestParam，@RequestBody区别，使用postman请求
获取参数 SpringBoot提供的获取参数注解包括:@PathVariable,@RequestParam,@RequestBody,三者的区别如下表: 一:后端接口什么都不加 postman请求后 ...
计算机前后端接口,看看别人后端API接口写得，那叫一个优雅！
在分布式.微服务盛行的今天,绝大部分项目都采用的微服务框架,前后端分离方式.题外话:前后端的工作职责越来越明确,现在的前端都称之为大前端,技术栈以及生态圈都已经非常成熟:以前后端人员瞧不起前端人员,那 ...
05_02_拉钩教育课程管理系统项目前后端接口联调
任务三前后端项目接口联调 1.联调准备 1.1 运行后台项目 clean 清空项目的编译文件 compile 重新编译项目将项目部署到 tomcat 项目名为: lagou_edu_home 端口 ...
如何使用微信开发者工具调试前后端接口
在微信小程序中,如果前后端分离开发的话,是需要通过接口来进行交互的, 因此在联系不到后台的情况下,写前端的我们应当如何测试自己的页面呢?方法如下: 微信小程序前端与后台交互的时候使用的是request ...
程序开发中：什么是前后端分离？你搞清楚了吗？
今天这篇文章来分析一下什么是前后端分离的相关知识,很多小伙伴不清楚到底什么是前端,什么是后端,什么是前后端分离.在说前后端分离之前,我们先要弄清楚这几个概念,大家可能经常听到前端,后端或者是大前端的一 ...
SSM+JSP+Bootstrap+Ajax小实例（员工CRUD系统）（五：员工查询前后端（请求返回json的方式））
原文再续,书接上回.上次我们讲了怎么把用户信息放到model里,然后用jsp+bootstrap做一个简单又不丑陋的界面去展示,但是现在讲究前后端分离,所以我们的接口返回一个json才是如今的王道,这 ...

中亿丰数字前后端接口请求说明书