[ADP-365] 自定義狀態碼

指導方針

避免自定義狀態碼

• 禁止(MUST NOT)創建自定義 HTTP 狀態碼。

  TIP

  RFC 9110 定義「狀態碼是通用的；它們可能適用於任何資源，而不僅僅是特定的媒體類型、資源類型或 HTTP 應用程式。因此，建議在不特定於單一應用程式的文件中註冊新的狀態碼。」

  雖然 HTTP 狀態碼列表是可擴展的，但我們不應該(SHOULD NOT)自行創建自定義代碼。這可以避免當未來定義了相同用途的新標準狀態碼時產生潛在衝突。

  RFC 9457 (以及相關的 ADP)提供了更多為什麼不建議為自定義錯誤建立單獨編號系統的理由。

  因此，儘管 RFC 9110 允許自定義狀態碼，但我們禁止為特定應用程式創建新的狀態碼，以防止歧義。

• 應該(SHOULD)使用 RFC 7231/RFC 9110 和其他相關 RFC 中定義的標準 HTTP 狀態碼。

使用問題詳情

• 當標準狀態碼不足以描述時，應該使用問題詳情(RFC 9457)來提供更具體的錯誤資訊。
• 可以定義自定義問題類型來表示特定應用程序的錯誤。有關自定義問題類型的指導，請參見 ADP-403: 問題類型設計。

示例

HTTP/1.1 400 Bad Request
Content-Type: application/problem+json

{
  "type": "https://example.com/probs/invalid-user-input",
  "title": "無效的用戶輸入",
  "status": 400,
  "detail": "提供的電子郵件地址格式無效。",
  "instance": "/users/create"
}

文件

• 必須(MUST)在 API 文件中記錄所有使用的 HTTP 狀態碼及其相關的問題詳情。
• 應該(SHOULD)在 API 文件中提供錯誤回應的示例。
• 應該(SHOULD)在公用的 OpenAPI problems.yaml 中加入錯誤回應方便共用，請參閱 ADP-767。

理由

自定義狀態碼可能導致互操作性問題，並使 API 消費者感到困惑。通過使用標準狀態碼和問題詳情，我們可以確保更好的兼容性，並提供一種更標準化的方式來傳達錯誤和異常情況。

參考資料

• RFC 7231: HTTP/1.1 語義和內容
• RFC 9110: HTTP 語義
• RFC 9457: HTTP API 的問題詳情
• ADP-403: 問題類型設計

Changelog

• 2025.01.16: Add reasoning for avoiding custom status code.