[ADP-406] 啓發性問題類型集合

概述

雖然 RFC 9457 沒有提供許多問題類型樣本，但我們根據 RFC 9457 中的指南 延伸設計了一些問題類型，可以用作內部錯誤設計註冊參考。

問題類型

驗證錯誤

HTTP 422 代表無法處理的內容。我們可以在其上創建一個新的錯誤類型 validation-error，因為指出客戶端請求問題是很常見的。

HTTP/1.1 422 Unprocessable Content
Content-Type: application/problem+json
Content-Language: en

{
  "type": "https://example.com/problems/validation-error",
  "title": "Validation Error",
  "status": 422,
  "detail": "One or more fields are invalid.",
  "instance": "/errors/12345",
  "errors": [
    {
      "in": "body",
      "path": "#/json/pointer/to/path",
      "detail": "should be one of the following values...",
      "details": [{
        "key": "role",
        "message": "should be one of the following values:..."
      }]
    },
    {
      "in": "query",
      "path": "page",
      "detail": "must be a positive integer",
      "details": [{
        "key": "page",
        "message": "must be a positive integer"
      }]
    }
  ]
}

使用場景：當客戶端提交的數據不符合 API 預期的格式或規則時。

超出速率限制

HTTP 429 代表請求過多，我們可以創建一個新的錯誤類型 rate-limit-exceeded，因為在不同產品/應用程序中限制 API 使用是非常常見的。

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 3600
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1625247600

{
  "type": "https://example.com/problems/rate-limit-exceeded",
  "title": "Rate Limit Exceeded",
  "status": 429,
  "detail": "You have exceeded the allowed number of requests. Please try again later.",
  "instance": "/errors/991122"
}

標頭欄位說明請參閱 ADP-138

使用場景：防止 API 濫用，確保公平使用，並保護服務器資源。

支付相關錯誤

資金不足

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

{
  "type": "https://example.com/problems/insufficient-funds",
  "title": "Insufficient Funds",
  "status": 400,
  "detail": "Your account does not have enough funds to complete this transaction.",
  "instance": "/transactions/12345",
  "balance": 50.00,
  "requiredBalance": 100.00
}

超出交易限額

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
Content-Language: en

{
  "type": "https://example.com/problems/transaction-limit-exceeded",
  "title": "Transaction Limit Exceeded",
  "status": 403,
  "detail": "You have exceeded your daily transaction limit.",
  "instance": "/transactions/67890",
  "transactionLimit": 1000.00,
  "attemptedAmount": 1200.00,
  "resetTime": "2024-07-16T00:00:00Z"
}

無效的支付方式

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

{
  "type": "https://example.com/problems/invalid-payment-method",
  "title": "Invalid Payment Method",
  "status": 400,
  "detail": "The provided payment method is invalid or expired.",
  "instance": "/payments/45678",
  "paymentMethod": "Credit Card",
  "cardLastFour": "1234"
}

使用場景：處理各種支付相關問題。

用戶權限相關錯誤

權限不足

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
Content-Language: en

{
  "type": "https://example.com/problems/insufficient-permissions",
  "title": "Insufficient Permissions",
  "status": 403,
  "detail": "You do not have the necessary permissions to access this resource.",
  "instance": "/resources/abc123",
  "user_id": "user-12345",
  "required_permission": "admin"
}

帳戶已停用（被封禁）

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
Content-Language: en

{
  "type": "https://example.com/problems/account-disabled",
  "title": "Account Disabled",
  "status": 403,
  "detail": "Your account has been disabled. Please contact support for assistance.",
  "instance": "/login",
  "userId": "user-67890",
  "supportContact": "support@example.com"
}

角色權限不足

HTTP/1.1 403 Forbidden
Content-Type: application/problem+json
Content-Language: en

{
  "type": "https://example.com/problems/role-insufficient",
  "title": "Role Insufficient",
  "status": 403,
  "detail": "Your current role does not grant you access to this resource.",
  "instance": "/resources/xyz789",
  "userId": "user-54321",
  "userRole": "basic",
  "requiredRole": "manager"
}

服務器錯誤

HTTP/1.1 500 Internal Server Error
Content-Type: application/problem+json
Content-Language: en

{
  "type": "/problems/invalid-permission",// replace specific code
  "title": "Invalid permission",
  "status": 500,
  "detail": ".....",
  "errors": []
}