API 超时重试与重复提交：先找回原请求状态

提交前写状态，恢复时读同一条记录

给每个业务操作一个稳定 ID，例如订单中的这次生成任务；调用者或租户也要使用稳定 scope。重试、重启、换 Key 后仍使用原 ID。输入指纹用于发现“同一个 ID 却换了任务内容”，不会把 API Key 写入记录。

1. 1.

   取得本地提交权

   在同一个状态目录独占创建操作记录。相同调用者、相同业务 ID 的并发请求只允许一个提交者。

2. 2.

   先持久化 submitting

   写入输入哈希、接口、时间和状态，再发一次 POST。崩溃留下 submitting 也按未知结果核对。

3. 3.

   保存已知结果或 unknown

   保存 HTTP 状态、脱敏请求 ID、视频 task ID；超时和无效响应不会自动重提。

4. 4.

   恢复前检查已有记录

   成功记录不再次生成；已有视频 ID 继续查询；unknown 与 rejected 都保留，人工核对后再决定新的操作。

{
  "protocol": "chat",
  "state": "unknown",
  "reason": "timeout-network-or-invalid-response",
  "httpStatus": null,
  "requestId": null,
  "taskId": null,
  "billedUsd": null
}

请求 ID 帮助对照日志，task ID 用于查询远端任务，两者不能互换。状态文件不保存 Key、提示词或响应正文；返回的原始 data 仍可能含业务内容，应用需要私下保存和脱敏。输入哈希不是加密。

用离线故障证明：未知状态不会重提

下载 ZIP 后进入 tokenba-api-kit 目录，先运行下面的现成 demo。它模拟响应丢失，并验证同 task ID 查询；不会读取真实 Key 或调用付费模型。

npm test
npm run test:python
node examples/recovery-demo.mjs
python3 examples/recovery-demo.py

{
  "evidence": "OFFLINE MOCK ONLY",
  "actualNetworkRequests": 0,
  "simulatedPosts": 1,
  "firstState": "unknown",
  "repeatBlocked": true
}

import { mkdtemp, rm } from "node:fs/promises";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { submitOnce } from "./src/recovery.mjs";

const stateDir = await mkdtemp(join(tmpdir(), "recovery-demo-"));
let simulatedPosts = 0;
const context = {
  stateDir, callerScope: "offline-demo", operationId: "order-001",
  fetchImpl: async () => {
    simulatedPosts++;
    throw new Error("OFFLINE MOCK: response lost after acceptance");
  },
};
try {
  const input = { model: "mock-model", key: "offline-fixture-credential" };
  const first = await submitOnce(input, context);
  const repeat = await submitOnce(input, context);
  console.log({ evidence: "OFFLINE MOCK ONLY", actualNetworkRequests: 0,
    state: first.record.state, repeatBlocked: repeat.reused, simulatedPosts });
} finally { await rm(stateDir, { recursive: true, force: true }); }

from tempfile import TemporaryDirectory
from request_recovery import submit_once

posts = [0]
def lost_response(*args):
    posts[0] += 1
    raise TimeoutError("OFFLINE MOCK: response lost after acceptance")

with TemporaryDirectory() as state_dir:
    context = dict(state_dir=state_dir, caller_scope="offline-demo",
                   operation_id="order-001", send=lost_response)
    input_body = {"model": "mock-model"}
    first = submit_once("chat", input_body, "offline-fixture-credential", **context)
    repeat = submit_once("chat", input_body, "offline-fixture-credential", **context)
    print({"evidence": "OFFLINE MOCK ONLY", "actualNetworkRequests": 0,
           "state": first["record"]["state"], "repeatBlocked": repeat["reused"],
           "simulatedPosts": posts[0]})

本地验证覆盖超时、错误状态持久化、重复提交、输入碰撞、Key 轮换、进程崩溃、凭据隔离和同一视频 ID 恢复。离线 mock 不能证明真实服务端去重、费用、取消语义或生产成功率。实际运行环境为 Node 24.14.0、Python 3.14.3；最低声明版本未逐一实测。

先关掉 SDK 隐藏的重试

2026-10-07 核对官方文档：OpenAI 与 Anthropic 的 Node/TypeScript、Python SDK 对部分错误默认再重试 2 次，包括连接错误、408、409、429 和 5xx；超时也会进入重试。应用再包一层 retry，实际尝试次数可能继续增加。

测试提交恢复时，先显式关闭 SDK 自动重试，再检查应用和代理层策略。Node 的 timeout 单位为毫秒，Python 为秒；以下只展示配置，不会在网页发送请求。

const client = new OpenAI({
  apiKey: process.env.tokenba_API_KEY,
  baseURL: "https://api.apizt.com/v1",
  maxRetries: 0,
  timeout: 30_000,
});

// Anthropic 使用 API host；SDK 按 Messages 协议构造路径
const anthropic = new Anthropic({
  apiKey: process.env.tokenba_API_KEY,
  baseURL: "https://api.apizt.com",
  maxRetries: 0,
  timeout: 30_000,
});

client = OpenAI(
    api_key=os.environ["tokenba_API_KEY"],
    base_url="https://api.apizt.com/v1",
    max_retries=0, timeout=30.0,
)
anthropic = Anthropic(
    api_key=os.environ["tokenba_API_KEY"],
    base_url="https://api.apizt.com",
    max_retries=0, timeout=30.0,
)

30 秒是这个示例的等待配置，不是模型完成时间保证。包内可选 SDK 示例没有接入持久化门禁，也未安装实测；核心故障 demo 使用原生传输模块。实际接入要锁定 SDK 版本并记录版本号，逐项验收协议。Messages 使用 2023-06-01，视频使用 /api/v3；/v1 路径不是 SDK 版本。

• OpenAI Node SDK：重试与超时
• OpenAI Python SDK：重试与超时
• Anthropic TypeScript SDK：默认重试
• Anthropic Python SDK：默认重试

视频恢复只查原来的 task ID

Seedance 创建返回 ID 后，先保存，再等待。查询超时不等于视频取消；继续查询同一任务即可。创建 POST 超时却没有 ID 时，先查任务历史，不能直接换 ID 再生成。

node examples/video-task.mjs --mode query --operation video-order-001
node examples/video-task.mjs --mode query --operation video-order-001 --run

python3 examples/video-task.py --mode query --operation video-order-001
python3 examples/video-task.py --mode query --operation video-order-001 --run

先前任务须由同一种语言、相同 operation ID、原状态目录创建。每个 query 只做一次 GET，不自动循环。succeeded 后保存下载地址和 MP4；下载器单独运行，不向 CDN 发送 API Key。生成失败、过期或取消也保留原 task ID，再核对账单。

本地防重复的边界，要写进应用

本包约束共享同一完整本地状态目录的进程，不提供远端恰好一次保证。多机服务需要统一存储、唯一约束与访问控制；磁盘损坏、掉电、状态目录丢失和服务端超时后的执行情况仍需核对。不要删 unknown 文件或更换业务 ID 来解锁。

本包没有发送 Idempotency-Key，也没有证明 apizt 所有接口、通道与上游统一支持它。只有接口明确说明幂等范围、保存期限、参数一致性和计费语义后，才能按那份契约使用。

RFC 9110 要求：非幂等请求只有在能确认可安全重复，或原请求没有应用时，才适合自动重试。客户端超时本身不足以满足这个条件。

此版本未做付费 API 调用、真实超时复现或生产日志验证。服务端执行、取消、实扣、可选 SDK 的运行兼容性和最低版本矩阵仍待核对。源码按 MIT 提供，GitHub / npm 公共发布尚未完成。