REST API v1 · 開發者

錯誤與錯誤代碼

錯誤一律以 JSON 回傳,內含穩定且可供程式判讀的 error 代碼,以及給人閱讀的 message。請依據 error 與 HTTP 狀態來判斷處理方式,訊息文字是寫給人看的,之後可能會變動。

開發者文件
本頁目錄

錯誤格式

所有錯誤回應的結構都相同:{ "error": CODE, "message": "…" }。部分代碼會附加有助於處理的欄位,例如 issues(哪些內容無效)、required(缺少的權限範圍)、balance、feature 或 retryAfter。

回應 · 400
HTTP/1.1 400 Bad Request

{
  "error": "INVALID_REQUEST",
  "message": "Invalid body",
  "issues": [{ "path": "body.amount", "message": "Number must be greater than or equal to 1" }]
}
回應 · 409
HTTP/1.1 409 Conflict

{ "error": "INSUFFICIENT_FUNDS", "message": "The member does not have enough to remove this amount", "balance": 40 }

在 issues 中,每個 path 都以它所指的請求部分開頭:params.、query.、body. 或 header.。

所有錯誤代碼

API 參考文件中的每個端點,都會列出它可能回傳的代碼。完整清單如下:

錯誤碼
HTTP代碼說明
400INVALID_REQUESTID、查詢參數、標頭或內容無效;issues 會列出問題所在
400INVALID_JSON內容不是有效的 JSON
401UNAUTHORIZED缺少 Authorization 標頭,或格式不正確
401INVALID_API_KEY此金鑰不存在
401API_KEY_REVOKED此金鑰已在控制台中被撤銷
401API_KEY_EXPIRED此金鑰已過期
402PLAN_LIMIT伺服器的方案不涵蓋此操作:已達到 limit 上限,或缺少 flag 功能
403BROWSER_REQUESTS_NOT_ALLOWED請求來自瀏覽器(帶有 Origin 標頭)
403GUILD_MISMATCH此金鑰屬於另一個伺服器
403INSUFFICIENT_SCOPE金鑰缺少所需的權限範圍;required 會指出是哪一個
403GUILD_BLOCKED此伺服器已被 BotGG 封鎖
403SELF_DECISIONAPI 金鑰的建立者不能自行審核自己的申請或申訴
403MODERATOR_NOT_MEMBERAPI 金鑰的建立者已不在伺服器中(管理動作是以其名義執行的)
403MODERATOR_MISSING_PERMISSIONAPI 金鑰的建立者缺少此操作所需的 Discord 權限;required 會指出是哪一個
403HIERARCHY無法對該對象執行管理動作;reason 會說明原因(金鑰建立者本人、機器人、擁有者,或身分組的位階不低於建立者或機器人)
404NOT_FOUND未知的端點
404TICKET_NOT_FOUND伺服器中沒有此編號的客服單
404TRANSCRIPT_NOT_FOUND此客服單沒有已儲存的對話紀錄(仍在進行中、未啟用對話紀錄,或已被刪除)
404APPLICATION_NOT_FOUND伺服器中沒有此編號或 ID 的申請(或表單)
404APPEAL_NOT_FOUND伺服器中沒有此編號的停權申訴
404CASE_NOT_FOUND伺服器中沒有此編號的管理案件
404MODERATION_ACTION_NOT_FOUND沒有使用此 API 金鑰建立、且 ID 相符的管理動作
404BOT_NOT_IN_GUILDBotGG 不在此伺服器中
404MEMBER_NOT_FOUND該使用者不是此伺服器的成員
404XP_CHANGE_NOT_FOUND沒有使用此 API 金鑰建立、且 ID 相符的經驗值變更
404SHOP_STORE_NOT_FOUND伺服器中沒有此 ID 的商店
404SHOP_ITEM_NOT_FOUND伺服器中沒有此 ID 的商店商品
404SHOP_PURCHASE_NOT_FOUND伺服器中沒有此 ID 的購買紀錄
404GIVEAWAY_NOT_FOUND伺服器中沒有此 ID 的抽獎
404FLOW_NOT_FOUND伺服器中沒有此 ID 的流程
404FLOW_EXECUTION_NOT_FOUND伺服器中沒有此 ID 的流程執行紀錄
409FEATURE_DISABLED此端點使用的功能在伺服器上已關閉;feature 會指出是哪個功能
409BANK_DISABLED此伺服器已關閉銀行功能
409INSUFFICIENT_FUNDS餘額不足,無法扣除;balance 為目前的餘額
409SHOP_ITEM_UNAVAILABLE此商品目前無法購買或發放;reason 會說明原因(已停用、商店已關閉、已售完、數量限制、價格已變動、身分組、等級、已擁有該身分組)
409SHOP_ALREADY_REFUNDED此筆購買已經退款
409SHOP_ITEM_USED此商品已被使用;請用 force: true 退款
409ROLE_NOT_GRANTABLE機器人無法發放此商品的身分組(身分組不存在、位階高於機器人、權限過大,或 Discord 拒絕);未扣款
409GIVEAWAY_BAD_STATE抽獎目前的狀態不允許此操作;status 為目前的狀態
409FLOW_NOT_RUNNABLE只有以手動或 Webhook 觸發開始的流程才能執行;triggerType 為該流程的觸發類型
409FLOW_DISABLED此流程已關閉
409TICKET_CLOSED此客服單已經關閉
409ALREADY_DECIDED此申請或申訴已經做出決定;status 為該決定
409NOT_BANNED該使用者並未被此伺服器停權
409BOT_MISSING_PERMISSIONS機器人缺少此操作所需的 Discord 權限;missing 會列出缺少的權限
413PAYLOAD_TOO_LARGE請求內容太大
415UNSUPPORTED_MEDIA_TYPE內容不是以 application/json 傳送
422IDEMPOTENCY_KEY_REUSED此冪等性金鑰已用於另一個不同的請求
422BOT_ACCOUNT機器人帳號不能持有餘額
422BALANCE_LIMIT此變更會超出伺服器的餘額限制
429RATE_LIMITED請求過多;請等待 Retry-After 秒(也在 retryAfter 欄位中)
500INTERNAL我們這邊發生了問題
503SERVICE_UNAVAILABLE無法連線到 Discord,或 BotGG 已暫時停用此功能;請稍後再試

哪些錯誤可以重試

  • 429 RATE_LIMITED 與 503 SERVICE_UNAVAILABLE:請等待 Retry-After 標頭(也在 retryAfter 欄位中)指定的秒數後再重試。
  • 500 INTERNAL 與網路錯誤:請以退避方式重試。寫入操作請附上 Idempotency-Key,這樣重試時就不會重複套用同一個變更。
  • 其他 4xx 錯誤重試同一個請求也不會成功,請先修正請求、金鑰或伺服器設定。

準備好讓你的伺服器升級了嗎?

免費新增 BotGG,再到網頁控制台開啟需要的功能。