错误代码

了解常见的 LEAPERone API 错误代码、HTTP 状态响应、计费失败、速率限制、重试处理和客户端恢复方法。

所有 API 错误都会返回包含 error 对象的 JSON 响应体。请结合 HTTP 状态码和 error.code 字段判断错误原因。

错误响应格式

错误响应示例

{
  "error": {
    "message": "Rate limit exceeded. Please slow down.",
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded"
  }
}

错误代码参考

状态码	含义	处理方法
400	请求错误	检查请求体格式和必填字段。
401	未授权	检查 API 密钥是否有效，并确认已放入 `Authorization` 请求头。
402	余额不足	前往 Dashboard 充值。
404	未找到	检查端点 URL 和相关资源 ID。
410	资源已失效	资源已经过期，例如超过 30 天的图像生成任务。
429	触发速率限制	降低请求速度并实现退避重试。参阅速率限制。
500	服务器错误	稍后重试。如果问题持续存在，请联系支持团队。

重试策略

并非所有错误都适合重试。可以参考下表：

状态码	可重试？	说明
400	否	修正请求后再重试。
401	否	修正 API 密钥或身份验证配置。
402	否	充值后再重试。
404	否	修正 URL 或资源 ID。
410	否	资源已经永久失效。
429	是	按照 `Retry-After` 请求头指定的时长等待。
500	是	使用指数退避。

指数退避

对于可重试错误，请使用指数退避，避免给 API 造成过大压力：

使用指数退避重试

async function requestWithRetry(fn, maxRetries = 5) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const response = await fn();

    if (response.ok) return response;

    // Only retry on 429 or 5xx
    if (response.status !== 429 && response.status < 500) {
      throw new Error(`Request failed with status ${response.status}`);
    }

    if (attempt < maxRetries) {
      const backoff = Math.min(1000 * 2 ** attempt, 30000);
      const jitter = Math.random() * 1000;
      await new Promise((r) => setTimeout(r, backoff + jitter));
    }
  }

  throw new Error("Max retries exceeded");
}

退避等待时间应始终加入随机抖动，避免大量客户端在同一时刻同时重试。

错误响应格式

错误代码参考

重试策略

指数退避

目录