运行与排障 · 2026-09-01 · HippoAPI Documentation Team

错误处理与重试

识别 API 错误，保留必要的排障信息，并且只重试可安全重复的临时故障。

错误响应格式

非 2xx 响应使用带有人类可读消息的错误对象，并且可能包括类型、代码或请求 ID。将 HTTP 状态视为第一个分类信号并保留请求 ID（如果存在）。

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

状态码与处理方式

状态码	含义	应用处理方式
400	请求、模型、字段无效或参数不受支持。	修复请求。不要以不变的方式重试同一请求体。
401	API 密钥丢失、格式错误、过期、禁用或无效。	更正或旋转密钥。不要自动重试。
403	账号、密钥、IP、组、模型不合法。	检查访问控制和模型可用性。
402	余额或额度不足。	在发送更多请求之前检查钱包和密钥配额。
404	未找到端点或模型资源。	检查Base 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 密钥。如果您已经分享或公开了该信息，请在继续调查之前将其撤消。