# Agent 重试一次 API，同一笔订单退了两次款

> 超时、有节制的重试和每个操作固定一个幂等键，约 80 行 TypeScript，今天就能用到项目里。

原文: https://fdetimes.net/zh/guides/typescript-agent-api-timeout-retry-idempotency/

一笔订单退了两次款，财务团队第二天早上才发现。设想一位刚到客户现场第二周的前线部署工程师（FDE）。团队部署的客服 Agent 有一个名为 `createRefund` 的工具，它调用客户内部的退款 API。某天下午网络不稳定，第一次请求没有收到响应，Agent 又试了一次，钱就退出去了两遍。

问题不在模型，而在包装 `fetch` 的那十几行代码。大家都觉得写这几行是杂活。对 FDE 来说，API 调用层是 Agent 接触客户真实资金、库存和数据的地方，这段代码必须一次写对。

这一层需要三样东西：超时、有节制的重试和幂等键。下文逐一讲解，最后把它们合成一个完整的 TypeScript 函数，可以直接复制，按自己的项目修改。

## 为什么简单重试很危险

Amazon Builders' Library 说得很直接：有副作用的 API，除非支持幂等，否则重试并不安全。退款请求超时后，客户端无法判断服务器是否已经处理。可能数据包根本没送到，也可能钱已经转出，只是响应在返回途中丢了。

幂等键解决的正是这种不确定性。Stripe 的文档写道，发生连接错误时，可以放心重发请求，不必担心创建第二个对象或把一次更新执行两遍。

机制很简单。对每个键，Stripe 会保存第一次请求的状态码和响应体，无论成功还是失败，之后每次重复请求都返回同样的结果。

“无论失败”这几个字很关键。按 Stripe 的说法，如果第一次尝试返回 500，用同一个键重试拿到的还是那个 500。因此，用旧键重试主要适用于失败发生在传输途中的情况，比如超时或连接断开，也就是客户端根本没收到任何结果的时候。

**要点:** 幂等键属于业务操作，而不属于某一次调用。

## 超时该设多长？

默认值通常远超 Agent 的需要。OpenAI 的 Node SDK 默认超时为 10 分钟，对耗时较长的模型调用来说合理，但查询订单的 API 绝不该等这么久。

Amazon 给出了一种有依据的选法。先确定能接受多大比例的“误判”超时，即多等一会儿本可成功的请求，再取下游服务对应的延迟百分位数，例如 p99.9。

如果退款 API 的 p99.9 是 1.2 秒，把超时设在 1.2 秒左右，就意味着接受约 0.1% 的请求被不必要地中断。

在 Node 中不需要用 `setTimeout` 自己拼。`AbortSignal.timeout()` 返回一个到时自动中止的信号，触发时以名为 `TimeoutError` 的 `DOMException` 中止。这样代码就能区分超时和用户主动取消，这两种情况需要不同的处理。

## 重试几次才够？

OpenAI 的 SDK 是不错的参考设计。根据其 README，它会自动重试两次，使用较短的指数退避，默认重试 408、409、429 错误、所有 500 及以上的错误以及连接错误。它不重试 400 或 401，因为重发同样的请求不会改变结果。

只有退避还不够，还要加抖动。Amazon 对抖动的解释是：在等待时间里加一点随机性，让重试在时间上分散开。没有抖动，一千个同时失败的 Agent 会话会在同一时刻重试，再次把服务压垮。

最大的危险是多层叠加重试。Amazon 举过一个例子：一个五层系统中每层都独立重试，数据库负载被放大 243 倍。

反推一下，243 是 3 的 5 次方，相当于每层最多尝试三次。Amazon 的解决办法是用令牌桶在本地限制重试：令牌用完就停止重试，把错误向上抛。

## TypeScript 完整实现

下面的 `callApi` 函数把三者结合在一起。注意生成键的那一行：它放在循环之外。

```ts
import { randomUUID } from "node:crypto";

type Method = "GET" | "POST" | "DELETE";
interface CallOptions {
  method: Method;
  url: string;
  body?: unknown;
  timeoutMs: number;          // 取自下游 API 的 p99.9
  maxRetries?: number;        // 默认为 2
  idempotencyKey?: string;    // 如果操作已有键，就传进来
  signal?: AbortSignal;       // 来自 Agent 或用户的取消信号
}

// 令牌桶：最多 10 次重试，每秒补充 1 个令牌
class RetryBudget {
  private tokens = 10;
  constructor() {
    setInterval(() => (this.tokens = Math.min(10, this.tokens + 1)), 1000).unref();
  }
  take(): boolean {
    if (this.tokens <= 0) return false;
    this.tokens--;
    return true;
  }
}
const budget = new RetryBudget();

// 带键的请求：不重试 5xx，服务器已保存结果，会返回同样的错误
const isRetryableStatus = (s: number, hasKey: boolean) =>
  s === 408 || s === 409 || s === 429 || (!hasKey && s >= 500);

const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
const backoff = (attempt: number) =>
  Math.random() * Math.min(5000, 200 * 2 ** attempt); // 抖动

export async function callApi(opts: CallOptions): Promise<Response> {
  const maxRetries = opts.maxRetries ?? 2;
  // 整个操作只生成一次；只有 POST 带键
  const key =
    opts.method === "POST" ? opts.idempotencyKey ?? randomUUID() : undefined;

  for (let attempt = 0; ; attempt++) {
    // 每次调用有独立的超时，并与调用方的取消信号合并
    const timeout = AbortSignal.timeout(opts.timeoutMs);
    const signal = opts.signal ? AbortSignal.any([opts.signal, timeout]) : timeout;
    try {
      const res = await fetch(opts.url, {
        method: opts.method,
        headers: {
          "Content-Type": "application/json",
          ...(key ? { "Idempotency-Key": key } : {}), // 请求头名称取决于具体 API
        },
        body: opts.body ? JSON.stringify(opts.body) : undefined,
        signal,
      });
      const canRetry =
        isRetryableStatus(res.status, key !== undefined) &&
        attempt < maxRetries &&
        budget.take();
      if (!canRetry) return res;
      await res.body?.cancel(); // 重试前丢弃响应体，释放连接
    } catch (err) {
      // 调用方主动取消：立即停止，不重试
      if (opts.signal?.aborted || attempt >= maxRetries || !budget.take()) throw err;
      // 其余情况是 TimeoutError 或网络错误：用同一个键重发
    }
    await sleep(backoff(attempt));
    if (opts.signal?.aborted) throw opts.signal.reason;
  }
}
```

回到那笔退款。第一次调用超时，catch 块收到 `TimeoutError`，函数随机等待一段时间后用同一个键重发。如果服务器已经处理过上一次请求，就返回保存的结果，不会再退第二次款。

修改这个函数时，有两个小细节值得保留。调用方的取消信号通过 `AbortSignal.any()` 与超时合并，Agent 中途被停止时，函数会立即退出，而不是继续重试。另外，为重试而放弃的响应会取消其响应体，连接不会一直挂在连接池里。

这里的重试条件有一点比 OpenAI 的 SDK 更窄：带键的请求不重试 500 及以上的错误。原因就在前面讲的机制。对于像 Stripe 这样按键保存首次结果的 API，500 之后用同一个键重发，只会拿回同一个 500，白白消耗预算。

GET 和 DELETE 不带键，所以照常重试 5xx。如果客户的 API 处理键的方式不同，放宽这个条件前先问清楚。

当 409 表示与另一个并发请求冲突时，仍然值得重试。Stripe 指出，参数校验失败或请求与正在处理的请求冲突时，它不会保存结果，所以这些情况下重发是安全的。

## 现场常见错误

最常见的错误是在循环内生成键。每次重试都带着新键，服务器把它当成新操作，幂等实际上就失效了。

Agent 还会带来一个更隐蔽的变体：模型在后面的步骤里再次调用同一个工具，而调用层为这次调用生成了新键。如果编排器可能重跑某个步骤，就从该步骤的 ID 派生键，通过 `idempotencyKey` 传入。

第二个错误是用不同的参数复用同一个键。Stripe 会把新参数和原始请求比对，不一致就返回错误。它还可能在 24 小时后删除键，所以第二天重跑的任务不能依赖旧键。

第三个错误是给每个请求都加键。Stripe 说明 GET 和 DELETE 本身就是幂等的，给它们带键没有作用。键里也不应放邮箱或账号：Stripe 建议使用 UUID V4 或熵足够的随机字符串，最长 255 个字符，不含敏感数据。

最后一个错误最难发现：在 SDK 之上再叠加重试。如果你的工具封装了一个本身已会重试两次的客户端，Agent 的编排器又在外面重试，放大倍数在没人察觉时就已经成倍增长。只选一层负责重试，其他层全部关闭重试。

## 把这项技能写进简历

阅读 FDE 岗位描述时，留意与客户系统集成或生产环境可靠性相关的要求：这类代码正好可以放进你的经历里讲。

简历上不要只写“开发了调用 API 的 Agent”。要写清楚超时按哪个百分位数设定、由哪一层负责重试、如何用幂等阻止重复操作。

面试中被问到“如果创建订单的请求超时，你的 Agent 会怎么做？”，正好可以把上面的循环画出来。面试官会记住那个明白超时不等于失败、而是结果未知的候选人。

**本周动手试试:**

- 在你正在开发的 Agent 里挑一个发起 POST 调用的工具，用本文的 callApi 函数包装它，再写一个测试，模拟第一次调用超时。
- 数一数你的 Agent 在几层重试（SDK、你的调用层、编排器），把每层的尝试次数相乘，得出真实的放大倍数。
- 向客户要 Agent 最常调用的那个 API 的 p99.9 延迟，并据此设定超时。

## 信源

- [Idempotent requests | Stripe API Reference](https://docs.stripe.com/api/idempotent_requests)

- [Timeouts, retries, and backoff with jitter (Amazon Builders' Library)](https://builder.aws.com/content/3EumjoZascWd1oZiEgL8ORlv3qE/timeouts-retries-and-backoff-with-jitter)

- [AbortSignal: timeout() static method - MDN](https://developer.mozilla.org/docs/Web/API/AbortSignal/timeout_static)

- [openai/openai-node README](https://github.com/openai/openai-node)
