一、簡介

服務器接口設計中最重要的環節之一便是接口請求格式和接口錯誤碼的定義了，通常情況下服務端會定義一些錯誤碼用以指示接口調用者或者用戶進行正確的操作。例如接口參數確實、參數非法、無權限訪問、用戶身份認證信息過期等等類似反饋。

二、請求格式

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

作者：扶云星程

總結

以上是生活随笔為你收集整理的中亿丰数字前后端接口请求说明书的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。