營運 · 2026-09-01 · HippoAPI Documentation Team

錯誤和重試

對 API 故障進行分類，捕獲有用的證據，並僅重試可以安全重複的瞬時請求。

錯誤回應形狀

非 2xx 回應使用帶有人類可讀訊息的錯誤對象，並且可能包括類型、代碼或請求 ID。將 HTTP 狀態視為第一個分類訊號並保留請求 ID（如果存在）。

{
  "error": {
    "message": "Error description (request id: ...)",
    "type": "new_api_error",
    "code": ""
  }
}

狀態代碼和操作

Status	意義	應用動作
400	請求、模型、欄位無效或參數不受支援。	修復請求。不要以不變的方式重試同一主體。
401	API 金鑰遺失、格式錯誤、過期、停用或無效。	更正或旋轉密鑰。不要自動重試。
403	帳號、金鑰、IP、群組、模型不合法。	檢查存取控制和模型可用性。
402	餘額或額度不足。	在發送更多請求之前檢查錢包和密鑰配額。
404	未找到端點或模型資源。	檢查基本 URL、端點路徑和確切的模型識別碼。
429	當前請求率或併發過高。	減少抖動並減少並發性。
5xx	平台或上游提供者故障。	重試安全請求，並有嚴格的嘗試限制；保留請求 ID。

使用有界指數退避

僅重試可能是暫時性的錯誤：連線失敗、HTTP 429 和選定的 5xx 回應。添加隨機抖動，以便許多工作人員不會同時重試。設定最大嘗試次數和總體截止日期。

const delaysMs = [500, 1000, 2000]

for (let attempt = 0; attempt <= delaysMs.length; attempt++) {
  try {
    return await callHippoAPI()
  } catch (error) {
    const status = error?.status
    const retryable = status === 429 || (status >= 500 && status < 600)
    if (!retryable || attempt === delaysMs.length) throw error
    const jitter = Math.floor(Math.random() * 250)
    await new Promise((resolve) => setTimeout(resolve, delaysMs[attempt] + jitter))
  }
}

記錄證據而不記錄秘密

請勿記錄包含個人、機密或受監管資料的Authorization 標頭、完整 API 金鑰或完整提示。在將錯誤轉發到可觀察性工具之前進行編輯。

UTC 時間戳和應用程式追蹤 ID。
HippoAPI 請求 ID（如果存在）。
HTTP 方法和端點路徑。
模型標識符、狀態代碼、持續時間和重試嘗試。
已編輯的錯誤摘要。

聯繫支援人員之前

使用最小的安全請求重現問題，確認模型出現在 GET /v1/models 中，並檢查使用日誌。然後向 [email protected] 提供時間戳記、端點、模型、HTTP 狀態、請求 ID 和經過編輯的請求摘要。

不要包含您的 API 金鑰。如果您已經分享或公開了該信息，請在繼續調查之前將其撤消。