永遠先判斷 ok。之後再讀 result（成功）或 description + error_code（失敗）。
總覽
所有方法回傳同一信封，你只需寫一個解析器並到處複用。
// 成功
{ "ok": true, "result": { ... } }
// 失敗
{ "ok": false, "description": "可讀的錯誤訊息", "error_code": 401 }
錯誤碼
碼 | 含義 | 常見原因與處理 |
400 | 請求無效 | 缺欄位或訊息不存在——修正參數。 |
401 | 未授權 | token 無效或已 revoke——檢查 token。 |
403 | 禁止 | 權限不足或訊息歸屬不符。 |
409 | 衝突 | Webhook 啟用時呼叫了 getUpdates。 |
429 | 限流 | 超過 30 req/s——退避後重試。 |
500 | 伺服端錯誤 | 依下方重試策略處理。 |
50001 | MP 業務錯誤 | 被業務層拒絕——查閱 |
501 | 未實作 | 目前不支援該方法（見方法矩陣）。 |
鑑權有效時，未知 API 方法會回傳 JSON 404，已知介面使用不支援的 HTTP 請求方式會回傳 JSON 405。鑑權和限流可能先回傳 401 或 429。
處理 409
呼叫 getWebhookInfo 確認 Webhook 配置。請勿自行執行 deleteWebhook——它是高危受控操作。請聯絡維護者處理衝突。
錯誤處理範例
async function readBotResponse(res) {
const data = await res.json().catch(() => null);
if (!res.ok || data?.ok !== true) {
const error = new Error("MPChat Bot API request failed");
error.httpStatus = res.status;
error.apiCode = data?.error_code;
throw error;
}
return data.result;
}
重試策略
遇到
429時先降低請求速率，再依有上限的指數退避重試。若回應提供等待時間，依該時間等候。請求逾時、連線中斷或回傳
5xx後，傳送操作可能已經成功。重送寫入請求前先用自己的操作記錄核對結果。重複呼叫sendMessage可能送出兩則訊息。遇到
400、401、403，先修正參數、憑證或權限。遇到
409，依下方的輪詢與 Webhook 指南檢查目前的投遞模式。
相關文章
錯誤上報中絕不記錄完整 token 或敏感欄位。脫敏規則見生產檢查清單。