API錯誤返回規范有哪些

# API錯誤返回規范有哪些

## 目錄
1. [引言](#引言)
2. [錯誤返回的基本結構](#錯誤返回的基本結構)
3. [HTTP狀態碼規范](#http狀態碼規范)
4. [錯誤碼設計原則](#錯誤碼設計原則)
5. [錯誤信息格式](#錯誤信息格式)
6. [常見錯誤分類](#常見錯誤分類)
7. [國際化與本地化](#國際化與本地化)
8. [安全注意事項](#安全注意事項)
9. [最佳實踐案例](#最佳實踐案例)
10. [總結](#總結)

---

## 引言
在API開發中，規范的錯誤返回機制是保證系統可維護性和用戶體驗的關鍵要素。據統計，超過40%的API相關問題源于不規范的錯誤處理。本文將深入探討API錯誤返回的完整規范體系。

（此處可擴展引入行業背景數據或案例）

---

## 錯誤返回的基本結構
標準的錯誤響應應包含以下核心字段：

```json
{
  "code": "INVALID_PARAMETER",
  "message": "Invalid email format",
  "details": {
    "field": "email",
    "requirement": "RFC 5322 format"
  },
  "trace_id": "a1b2c3d4-5678-90ef"
}

必要字段說明

HTTP狀態碼規范

應嚴格遵循RFC 7231標準：

主要狀態碼分類

使用建議

1. 不要濫用200狀態碼返回錯誤
2. 5xx錯誤應包含可選的retry_after字段
3. 保持狀態碼與業務錯誤碼的語義一致

錯誤碼設計原則

命名規范

• 采用大寫下劃線格式（例：RATE_LIMIT_EXCEEDED）
• 前綴區分模塊（例：AUTH_/PAYMENT_）

分級體系

建議采用三級分類：

<服務標識>_<模塊>_<具體錯誤>
└── USER_SERVICE
    ├── AUTH_INVALID_TOKEN
    └── PROFILE_EML_EXISTS

保留碼范圍

錯誤信息格式

消息內容要求

• 避免暴露敏感信息（如SQL錯誤）
• 包含可操作建議（例：”請檢查郵箱格式”）
• 技術細節放入details字段

多語言支持

{
  "message": {
    "en": "Invalid parameter",
    "zh-CN": "參數無效"
  }
}

常見錯誤分類

輸入驗證錯誤

{
  "code": "VALIDATION_ERROR",
  "message": "Request validation failed",
  "details": [
    {
      "field": "age",
      "error": "Must be positive integer"
    }
  ]
}

業務邏輯錯誤

{
  "code": "INSUFFICIENT_BALANCE",
  "message": "Account balance不足",
  "required_amount": 100.00,
  "current_balance": 80.00
}

系統錯誤

{
  "code": "DATABASE_TIMEOUT",
  "message": "系統繁忙，請稍后重試",
  "retryable": true,
  "retry_after": 30
}

國際化與本地化

實現方案

1. 通過Accept-Language頭識別語言
2. 錯誤碼與消息分離存儲
3. 動態加載消息模板

示例結構

errors:
  AUTH_FLED:
    en: "Authentication failed"
    zh: "認證失敗"
    ja: "認証に失敗しました"

安全注意事項

1. 信息泄露防護

   • 禁止返回堆棧跟蹤
   • 數據庫錯誤需脫敏處理

2. 限流信息暴露

   // 不建議
   {
    "remaining": 0,
    "reset_time": "2023-01-01T00:00:00Z"
   }
   

3. 錯誤分類策略

   • 客戶端錯誤（4xx）可顯示詳細信息
   • 服務端錯誤（5xx）應模糊處理

最佳實踐案例

GitHub API

{
  "message": "Validation Failed",
  "errors": [
    {
      "resource": "Issue",
      "field": "title",
      "code": "missing_field"
    }
  ],
  "documentation_url": "https://docs.github.com/rest/reference/issues#create-an-issue"
}

Stripe API

{
  "error": {
    "type": "card_error",
    "code": "expired_card",
    "doc_url": "https://stripe.com/docs/error-codes/expired-card"
  }
}

總結

完整的錯誤返回規范應包含： 1. 標準的HTTP狀態碼 2. 結構化的錯誤體 3. 明確的錯誤分類 4. 完善的安全控制 5. 可擴展的國際化方案

“好的錯誤處理不是事后補救，而是事先設計” —— Martin Fowler

（此處可加入參考文獻和擴展閱讀鏈接） “`

注：實際使用時可根據需要： 1. 補充具體行業的案例 2. 增加各字段的詳細示例 3. 插入架構圖或狀態轉換圖 4. 添加團隊內部的特殊規范要求