[ADP-406] Collection of Heuristic Question Types

Overview

Although RFC 9457 does not provide many sample question types, we have designed some question types based on the guidelines in RFC 9457 that can be used as a reference for internal error design registration.

Question Types

Validation Error

HTTP 422 represents Unprocessable Content. We can create a new error type validation-error, as it is common to point out issues with client requests.

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"
      }]
    }
  ]
}

Use case: When the data submitted by the client does not conform to the expected format or rules of the API.

Rate Limit Exceeded

HTTP 429 represents Too Many Requests. We can create a new error type rate-limit-exceeded, as it is common to limit API usage across different products/applications.

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"
}

For header field descriptions, please refer to ADP-138.

Use case: To prevent API abuse, ensure fair usage, and protect server resources.

Payment-Related Errors

Insufficient Funds

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
}

Transaction Limit Exceeded

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"
}

Invalid Payment Method

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"
}

Use case: To handle various payment-related issues.

User Permission-Related Errors

Insufficient Permissions

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"
}

Account Disabled (Banned)

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"
}

Role Insufficient

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"
}

Server Error

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": []
}