纸鸢 OCR

第一次打开是抱着试试看的心态，结果在第一步就卡了一会儿，后面才顺起来。

生产环境偶发 502，响应头里没有 `x-request-id`，而工单必须提供 request id 才能查，形成死循环，我只能自己抓包记录时间戳再去对，效率极低。

给 `from`、`to` 这类时间参数标注边界语义并统一成左闭右开；希望报表口径和账单完全一致。

缺少接口级的变更公告渠道，我们只能靠线上监控发现行为变化。

我当时的调用大概是这样：

const key = "run-" + jobId;
try {
  await client.agents.run({ idempotencyKey: key, input });
} catch (e: any) {
  if (e.status === 409) {
    // 超时重试撞上第一次的幂等键，任务其实还在跑
    const state = await client.agents.get(e.body.run_id);
    if (state.status === "done") return state;
  }
  throw e;
}

用之前特意没看教程，想试试不看说明能不能自己走通。

Webhook 签名文档写用 HMAC-SHA256、密钥是 `secret`，示例代码用 hex 编码，服务端实际发的是 base64，我按文档校验全部失败，线上回调积压了 40 分钟才定位到。

在 429 响应头里明确 `Retry-After` 的单位并给出示例；希望客户端退避逻辑一次写对，减少无效重试和重复请求。

同一个参数的取值在文档、SDK 类型和实际接口里是三套，很难对这套 API 建立信任。

本来只打算花十分钟看看，结果因为下面这个问题多折腾了半小时。

分页 `GET /v1/events?limit=100` 返回 100 条，`next_cursor` 却为 null，我以为到底了；后来发现总量有 3000 多条，只是服务端在 limit 大于 50 时干脆不返回游标。

让 `GET /v1/events` 在 `limit` 很大时也返回 `next_cursor` 和 `total`；我预期能安全做全量同步，不用改成 50 条一轮慢慢拉。

免费额度和速率限制挤在同一组响应头里，容量估算经常差一个数量级。

我当时的调用大概是这样：

try {
  const r = await client.chat.completions.create(req);
  return r.choices[0];
} catch (err) {
  const e = err as { status?: number; request_id?: string; message: string };
  logger.error("beehub call failed", {
    status: e.status,
    requestId: e.request_id ?? "missing",
    message: e.message,
  });
  throw err;
}