REST API v1 · 開發者
錯誤與錯誤代碼
錯誤一律以 JSON 回傳,內含穩定且可供程式判讀的 error 代碼,以及給人閱讀的 message。請依據 error 與 HTTP 狀態來判斷處理方式,訊息文字是寫給人看的,之後可能會變動。
開發者文件
本頁目錄
錯誤格式
所有錯誤回應的結構都相同:{ "error": CODE, "message": "…" }。部分代碼會附加有助於處理的欄位,例如 issues(哪些內容無效)、required(缺少的權限範圍)、balance、feature 或 retryAfter。
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" }]
}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 | 代碼 | 說明 |
|---|---|---|
| 400 | INVALID_REQUEST | ID、查詢參數、標頭或內容無效;issues 會列出問題所在 |
| 400 | INVALID_JSON | 內容不是有效的 JSON |
| 401 | UNAUTHORIZED | 缺少 Authorization 標頭,或格式不正確 |
| 401 | INVALID_API_KEY | 此金鑰不存在 |
| 401 | API_KEY_REVOKED | 此金鑰已在控制台中被撤銷 |
| 401 | API_KEY_EXPIRED | 此金鑰已過期 |
| 402 | PLAN_LIMIT | 伺服器的方案不涵蓋此操作:已達到 limit 上限,或缺少 flag 功能 |
| 403 | BROWSER_REQUESTS_NOT_ALLOWED | 請求來自瀏覽器(帶有 Origin 標頭) |
| 403 | GUILD_MISMATCH | 此金鑰屬於另一個伺服器 |
| 403 | INSUFFICIENT_SCOPE | 金鑰缺少所需的權限範圍;required 會指出是哪一個 |
| 403 | GUILD_BLOCKED | 此伺服器已被 BotGG 封鎖 |
| 403 | SELF_DECISION | API 金鑰的建立者不能自行審核自己的申請或申訴 |
| 403 | MODERATOR_NOT_MEMBER | API 金鑰的建立者已不在伺服器中(管理動作是以其名義執行的) |
| 403 | MODERATOR_MISSING_PERMISSION | API 金鑰的建立者缺少此操作所需的 Discord 權限;required 會指出是哪一個 |
| 403 | HIERARCHY | 無法對該對象執行管理動作;reason 會說明原因(金鑰建立者本人、機器人、擁有者,或身分組的位階不低於建立者或機器人) |
| 404 | NOT_FOUND | 未知的端點 |
| 404 | TICKET_NOT_FOUND | 伺服器中沒有此編號的客服單 |
| 404 | TRANSCRIPT_NOT_FOUND | 此客服單沒有已儲存的對話紀錄(仍在進行中、未啟用對話紀錄,或已被刪除) |
| 404 | APPLICATION_NOT_FOUND | 伺服器中沒有此編號或 ID 的申請(或表單) |
| 404 | APPEAL_NOT_FOUND | 伺服器中沒有此編號的停權申訴 |
| 404 | CASE_NOT_FOUND | 伺服器中沒有此編號的管理案件 |
| 404 | MODERATION_ACTION_NOT_FOUND | 沒有使用此 API 金鑰建立、且 ID 相符的管理動作 |
| 404 | BOT_NOT_IN_GUILD | BotGG 不在此伺服器中 |
| 404 | MEMBER_NOT_FOUND | 該使用者不是此伺服器的成員 |
| 404 | XP_CHANGE_NOT_FOUND | 沒有使用此 API 金鑰建立、且 ID 相符的經驗值變更 |
| 404 | SHOP_STORE_NOT_FOUND | 伺服器中沒有此 ID 的商店 |
| 404 | SHOP_ITEM_NOT_FOUND | 伺服器中沒有此 ID 的商店商品 |
| 404 | SHOP_PURCHASE_NOT_FOUND | 伺服器中沒有此 ID 的購買紀錄 |
| 404 | GIVEAWAY_NOT_FOUND | 伺服器中沒有此 ID 的抽獎 |
| 404 | FLOW_NOT_FOUND | 伺服器中沒有此 ID 的流程 |
| 404 | FLOW_EXECUTION_NOT_FOUND | 伺服器中沒有此 ID 的流程執行紀錄 |
| 409 | FEATURE_DISABLED | 此端點使用的功能在伺服器上已關閉;feature 會指出是哪個功能 |
| 409 | BANK_DISABLED | 此伺服器已關閉銀行功能 |
| 409 | INSUFFICIENT_FUNDS | 餘額不足,無法扣除;balance 為目前的餘額 |
| 409 | SHOP_ITEM_UNAVAILABLE | 此商品目前無法購買或發放;reason 會說明原因(已停用、商店已關閉、已售完、數量限制、價格已變動、身分組、等級、已擁有該身分組) |
| 409 | SHOP_ALREADY_REFUNDED | 此筆購買已經退款 |
| 409 | SHOP_ITEM_USED | 此商品已被使用;請用 force: true 退款 |
| 409 | ROLE_NOT_GRANTABLE | 機器人無法發放此商品的身分組(身分組不存在、位階高於機器人、權限過大,或 Discord 拒絕);未扣款 |
| 409 | GIVEAWAY_BAD_STATE | 抽獎目前的狀態不允許此操作;status 為目前的狀態 |
| 409 | FLOW_NOT_RUNNABLE | 只有以手動或 Webhook 觸發開始的流程才能執行;triggerType 為該流程的觸發類型 |
| 409 | FLOW_DISABLED | 此流程已關閉 |
| 409 | TICKET_CLOSED | 此客服單已經關閉 |
| 409 | ALREADY_DECIDED | 此申請或申訴已經做出決定;status 為該決定 |
| 409 | NOT_BANNED | 該使用者並未被此伺服器停權 |
| 409 | BOT_MISSING_PERMISSIONS | 機器人缺少此操作所需的 Discord 權限;missing 會列出缺少的權限 |
| 413 | PAYLOAD_TOO_LARGE | 請求內容太大 |
| 415 | UNSUPPORTED_MEDIA_TYPE | 內容不是以 application/json 傳送 |
| 422 | IDEMPOTENCY_KEY_REUSED | 此冪等性金鑰已用於另一個不同的請求 |
| 422 | BOT_ACCOUNT | 機器人帳號不能持有餘額 |
| 422 | BALANCE_LIMIT | 此變更會超出伺服器的餘額限制 |
| 429 | RATE_LIMITED | 請求過多;請等待 Retry-After 秒(也在 retryAfter 欄位中) |
| 500 | INTERNAL | 我們這邊發生了問題 |
| 503 | SERVICE_UNAVAILABLE | 無法連線到 Discord,或 BotGG 已暫時停用此功能;請稍後再試 |
哪些錯誤可以重試
429 RATE_LIMITED與503 SERVICE_UNAVAILABLE:請等待Retry-After標頭(也在retryAfter欄位中)指定的秒數後再重試。500 INTERNAL與網路錯誤:請以退避方式重試。寫入操作請附上 Idempotency-Key,這樣重試時就不會重複套用同一個變更。- 其他
4xx錯誤重試同一個請求也不會成功,請先修正請求、金鑰或伺服器設定。