錯誤處理與冪等性

標準 RFC 7807 錯誤結構、HTTP 狀態碼矩陣與 Idempotency-Key 冪等性規範。

Pinnacle API 遵循 RFC 7807 (Problem Details for HTTP APIs) 標準結構。所有接口返回語意化 HTTP 狀態碼與具體的錯誤代碼，並原生支援變更請求的冪等性重試。

標準錯誤格式 (RFC 7807)

當發生非 2xx 響應時，網關返回如下規格的結構化錯誤主體：

422 Unprocessable Entity 錯誤示範

{
  "type": "https://api.pinnacle-advisory.vg/errors/invalid_parameters",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "Field 'dataset_id' references a non-existent or inactive entity.",
  "instance": "/v1/analytics/jobs/req_88192301",
  "code": "INVALID_DATASET_ID",
  "timestamp": "2026-09-29T08:30:00Z",
  "invalid_fields": [
    {
      "field": "dataset_id",
      "reason": "Entity 'ds_non_existent' not found in project scope."
    }
  ]
}

常用 HTTP 狀態碼矩陣

HTTP 狀態碼	錯誤代碼 (Code)	語意場景與修復指引
400 Bad Request	MALFORMED_JSON	請求體語法錯誤或無法解析為 JSON，請檢查 Payload 格式。
401 Unauthorized	INVALID_API_KEY	API Key 遺失、已過期或撤銷，請重新核對 Authorization 標頭。
403 Forbidden	INSUFFICIENT_SCOPE	憑證權限不足，如讀取憑證嘗試發起變更或非涉密租戶越權訪問。
404 Not Found	RESOURCE_NOT_FOUND	請求的任務 ID、實體或拓撲藍圖不存在或已被歸檔。
409 Conflict	IDEMPOTENCY_CONFLICT	相同 Idempotency-Key 的不同請求正在並發執行，請等待前序處理完成。
422 Unprocessable	SCHEMA_VALIDATION_FAILED	參數類型不符或關鍵依賴關係校驗不通過（如時序預測時間步長為負數）。
429 Too Many Requests	RATE_LIMIT_EXCEEDED	請求頻率超出當前等級配額，請依據 Retry-After 標頭延遲重試。
500 Internal Error	INTERNAL_CALC_ERROR	Pinnacle 內部運算叢集異常，已自動觸發告警，請聯絡技術支援團隊。
503 Service Unavailable	MAINTENANCE_MODE	系統維護窗口期，請關注官方狀態頁通知並於維護後重試。

冪等性與指數退避重試策略

對於網絡抖動（502/503/504）或速率限制（429），客戶端應當採用帶隨機抖動（Jitter）的指數退避算法重試，同時保持相同的 `Idempotency-Key`：

退避公式與重試示例 (Python)

import time
import random

def exponential_backoff_retry(func, max_retries=5, base_delay=1.0):
    for attempt in range(max_retries):
        try:
            return func()
        except RetriableHttpError as err:
            if attempt == max_retries - 1:
                raise err
            # 指數退避 + 均勻隨機抖動
            delay = base_delay * (2 ** attempt) + random.uniform(0, 0.5)
            time.sleep(delay)

標準錯誤格式 (RFC 7807)

常用 HTTP 狀態碼矩陣

冪等性與指數退避重試策略

On this page