> ## Documentation Index
> Fetch the complete documentation index at: https://apione.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 请求跟踪、超时与重试

> 使用请求 ID 定位问题，并为超时、限流和上游波动设置安全重试。

生产环境应同时设置连接超时、总超时、重试上限和请求跟踪 ID。

## 请求 ID

记录 APIONE 响应中的请求标识。不同接口或线路可能返回 `X-Request-ID`、`X-Maxx-Trace-Id` 或 `X-Maxx-Request-ID`，请保留实际收到的字段名和值。反馈问题时提供请求时间和时区、模型 ID、完整端点、状态码、错误码及请求标识。

不要提交完整 API Key、敏感提示词或未脱敏文件。

![APIONE 请求明细与调用状态](https://mintcdn.com/apione/pAFvFGkbmcRZirTZ/images/ui/request-logs.png?fit=max\&auto=format\&n=pAFvFGkbmcRZirTZ\&q=85\&s=093db383e228008dc3c42cb6a7849d28)

控制台请求明细可按时间、来源、API Key 和请求 ID 筛选，并核对状态、耗时、Token 与费用。

## 何时重试

| 情况 | 建议 |
| - | - |
| 400、401、403、404 | 修正请求、鉴权、权限或路径，不自动重试 |
| 402 | 补充余额或调整额度，不自动重试 |
| 429 | 读取 `Retry-After`，等待后有限次数重试 |
| 5xx、网络中断 | 使用指数退避和随机抖动，设置最大次数 |

> [!WARNING]
>
> 创建图像或视频等可能计费的任务时，不要在结果未知时无限重试。先用请求 ID 或任务 ID 查询状态，避免重复创建。

## 超时建议

* 文本请求分别设置连接超时和读取超时。
* 流式请求以首个事件和持续读取为边界，不要套用过短的普通请求超时。
* 视频生成是异步任务。创建成功后轮询任务状态，不要让一个 HTTP 连接等待生成结束。

## 智能路由边界

APIONE 会在同一模型的可用线路间选择或切换。若模型、权限、余额或请求参数本身有误，切换线路不能解决问题。所有线路都不可用时，请求仍可能失败。

## 推荐的退避策略

首次失败后等待短时间，再按指数增加等待，并加入随机抖动，避免多个请求同时重试。总尝试次数应有限，业务侧还要设置总时间预算。

```text theme={null}
delay = min(baseDelay × 2^attempt + randomJitter, maxDelay)
```

下面的 Node.js 示例适用于可重放、已确认允许重试的请求。`maxAttempts` 包含首次请求；最后一次 HTTP 失败会保留原响应，便于读取状态码与错误正文。`Retry-After` 支持秒数和 HTTP 日期，缺失或无效时使用退避等待。

调用方应检查最终响应的 `ok` 状态，并按业务设置超时。请求体使用可重放的字符串或字节数据；SDK 已自动重试时，应统筹总尝试次数。

将下面两个 JavaScript 代码块依次合并，保存为 `example.mjs`。先按[快速开始](https://apione.ai/docs/quickstart.md)设置 `APIONE_API_KEY`，在同一终端运行 `node example.mjs`。使用 Node.js 18 或更高版本，内置 `fetch` 无需额外依赖。

```javascript theme={null}
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

function retryDelay(response, attempt) {
  const value = response?.headers.get("retry-after")?.trim();
  if (value) {
    const seconds = Number(value);
    if (Number.isFinite(seconds) && seconds >= 0) return seconds * 1000;
    const retryAt = Date.parse(value);
    if (Number.isFinite(retryAt)) return Math.max(0, retryAt - Date.now());
  }
  return Math.min(1000 * 2 ** attempt + Math.random() * 300, 8000);
}

async function requestWithRetry(url, options = {}, maxAttempts = 3) {
  if (!Number.isInteger(maxAttempts) || maxAttempts < 1) {
    throw new RangeError("maxAttempts must be a positive integer");
  }

  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    let response;
    try {
      response = await fetch(url, options);
    } catch (error) {
      if (options.signal?.aborted || attempt === maxAttempts - 1) throw error;
      await sleep(retryDelay(null, attempt));
      continue;
    }

    const retryable = response.status === 429 || response.status >= 500;
    if (!retryable || attempt === maxAttempts - 1) return response;

    const delay = retryDelay(response, attempt);
    await response.body?.cancel();
    await sleep(delay);
  }
}
```

### 读取请求标识

```javascript theme={null}
const apiKey = process.env.APIONE_API_KEY;
if (!apiKey) throw new Error("Set APIONE_API_KEY first");
const response = await requestWithRetry("https://api.apione.ai/v1/models", {
  headers: { Authorization: `Bearer ${apiKey}` },
  signal: AbortSignal.timeout(30_000),
});
const requestIds = Object.fromEntries(
  ["X-Request-ID", "X-Maxx-Trace-Id", "X-Maxx-Request-ID"]
    .map(name => [name, response.headers.get(name)])
    .filter(([, value]) => value)
);
console.log(response.status, requestIds);
if (!response.ok) {
  throw new Error(`HTTP ${response.status}: ${await response.text()}`);
}
```

## 防止重复创建

文本查询通常可以安全重试，但图像、视频或其他创建类请求可能已经被服务端接收。连接中断不代表任务没有创建。应用应保存以下信息：

| 信息 | 用途 |
| - | - |
| 本地业务请求 ID | 将用户操作与一次调用关联 |
| 实际返回的请求标识及字段名 | 向 APIONE 查询网关记录 |
| 视频任务 ID | 查询异步任务状态 |
| 创建时间与模型 | 判断是否为同一操作 |
| 请求参数摘要 | 去重，不保存敏感原文 |

状态未知时先查询记录或任务，不要立即重新创建。

## 超时分层

| 超时 | 控制什么 | 建议 |
| - | - | - |
| 连接超时 | 与网关建立连接 | 设置较短，失败后检查 DNS、代理和网络 |
| 首字节超时 | 等待模型开始返回 | 推理模型可能明显长于普通聊天 |
| 读取超时 | 相邻数据块等待时间 | 流式请求应允许持续读取 |
| 总超时 | 整次同步请求时间 | 到期后主动取消并记录请求 ID |
| 任务截止时间 | 异步媒体任务总等待 | 超时后停止高频轮询并保留任务 ID |

## 生产检查单

* 为测试和生产使用不同 API Key，便于限额、撤销和审计。
* 记录状态码、耗时、模型与请求 ID，不记录完整密钥。
* 限制最大并发和重试总量，避免故障期间放大流量。
* 对流式输出处理半途错误、客户端取消和不完整 JSON。
* 对媒体任务区分“创建成功”“生成成功”和“结果已下载”。
* 监控成功率、首字节时间、总耗时、429 与 5xx 比例。

下一步：[错误码与排查](https://apione.ai/docs/support/errors.md)、[视频任务](https://apione.ai/docs/api/videos.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.