錯誤碼速查（401 / 403 / 404 / 422 / 429 / 500）
toobo
上次更新 5 個月前
【這篇解決什麼問題】
你要在 API 呼叫失敗時快速定位問題，縮短除錯時間。
【標準錯誤格式】
通常會回傳：
【常見狀態碼】
401 Unauthorized
403 Forbidden
404 Not Found
422 Unprocessable Entity
429 Too Many Requests
500 Internal Server Error
【排查順序建議】
1) 先看狀態碼
2) 再看 message
3) 若是 422，逐欄位修正 errors
4) 針對 429 加入退避與重試上限
【下一步】
你要在 API 呼叫失敗時快速定位問題，縮短除錯時間。
【標準錯誤格式】
通常會回傳：
- message：錯誤摘要
- errors：欄位層級錯誤（常見於 422）
【常見狀態碼】
401 Unauthorized
- 認證失敗或 Token 問題
- 先檢查 Bearer Token 與權限
403 Forbidden
- Token 有效但缺少對應的 ability（權限不足）
- 確認 Token 是否包含所需的讀寫權限（如 orders:write）
404 Not Found
- 路徑或資源不存在
- 常見於 ID/編號拼錯或資源不在該商家範圍
422 Unprocessable Entity
- 請求格式正確但資料驗證失敗
- 依 errors 欄位修正資料
429 Too Many Requests
- 請求超過限制
- 依 Retry-After 或退避策略重試
500 Internal Server Error
- 伺服器端異常，與你的請求無關
- 請稍後重試，若持續發生請聯繫客服
【排查順序建議】
1) 先看狀態碼
2) 再看 message
3) 若是 422，逐欄位修正 errors
4) 針對 429 加入退避與重試上限
【下一步】
- 若常遇 429，請補讀 Rate Limit 文件
- 若常遇 401，請回看 API 認證與金鑰治理