錯誤與重試

WiseLink API v1 採用遵循 RFC 7807 思想的標準化 JSON 錯誤格式。所有非 2xx 的錯誤回應均包含機器可讀的 error.code、人類可讀的 error.message 以及全局追蹤標識 request_id。

統一錯誤響應結構

當 API 調用失敗時，服務端將返回標準結構的 JSON 實體：

標準錯誤回應範例 (HTTP 400 Bad Request)

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "regions 欄位不能為空，至少需要指定一個有效營運地區代碼。"
  },
  "request_id": "req_01HP8X9J23KQ7V"
}

HTTP 狀態	業務錯誤碼 (error.code)	原因描述	建議客戶端處置
400	VALIDATION_ERROR	必填欄位缺失、JSON 格式無效或字段類型不匹配	修正請求正文字段後重新提交
401	UNAUTHORIZED	缺少 Authorization 標頭或 Bearer Key 無效/過期	核對發放的 API Key 是否正確注入
403	FORBIDDEN	當前憑證無權訪問該接口（例如未開通 AI 服務）	聯繫 WiseLink 商務確認權限範圍
404	NOT_FOUND	URL 中指定的 task_id 或 assessment_id 不存在	檢查資源 ID 是否正確拼寫或屬於不同環境
409	IDEMPOTENCY_CONFLICT	同一個 Idempotency-Key 嘗試提交了不同的請求內容	若為新請求，生成全新的 UUID 作為冪等鍵
429	RATE_LIMITED	超出組織配額的併發調用頻率限制	降低發送速率，使用指數退避重試
500	INTERNAL_ERROR	WiseLink 服務端內部未知異常	保留 request_id 並聯繫技術支援反饋

WiseLink 的 POST 資源建立接口採用冪等性保護：

相同 Key + 相同內容：服務端將直接返回第一次成功建立的資源結果，HTTP 狀態碼通常保持一致，不會重復執行扣費或任務創建。
相同 Key + 不同內容：服務端識別到潛在的代碼邏輯衝突，直接返回 409 IDEMPOTENCY_CONFLICT。客戶端應在業務有更新時主動換用全新的 UUID 冪等鍵。

按 ID 精準查詢設計

API v1 的查詢端點均採用按資源唯一標識直接獲取的模式（如 GET /v1/ai/tasks/{task_id}）。由於不提供全量批次列表掃描接口，因此不使用分頁參數（如 page、limit）。客戶端應在建立資源時自行持久化對應的資源 ID。