高级

错误码

LinkHarbor 使用标准 HTTP 响应码表示 API 请求成功或失败。本页列出常见错误及处理方式。

错误响应格式

所有错误都遵循一致的 JSON 结构，并包含顶层 error 对象。

JSON

{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": "invalid_api_key"
  }
}

400

无效请求

请求体格式错误或缺少必填字段。

401

未授权

API 密钥无效、已过期、缺失，或使用了与当前接口不匹配的认证请求头。

402

额度不足

账户余额不足，无法完成该请求。

404

模型未找到

请求的模型 ID 不存在，或在您的区域不可用。

429

超过速率限制

请求过多。请在 Retry-After 响应头指定的时间后重试。

500

内部服务器错误

服务端发生意外错误。请使用指数退避重试。

502

上游供应商错误

上游 AI 供应商返回错误。仅在已配置路由或故障转移时，系统才可能尝试 fallback。

对于 5xx 错误，建议使用指数退避重试（1s、2s、4s）。对于 429 错误，如响应中包含 Retry-After，请遵循该响应头。

记录 HTTP 状态码、响应体、端点路径、模型 ID 和时间戳，便于排查和支持。
遇到 401 时，请确认 OpenAI 兼容调用使用 Authorization: Bearer；Anthropic 兼容调用使用 x-api-key 并携带 anthropic-version。
遇到连续 5xx 或 502 时，请使用退避重试，并确认所选上游模型/供应商是否可用。