结算状态未知时应该怎么办？

停止付款重试，核对原 Intent。settlement_unknown 表示一笔已经授权的付款可能到达了 x402 结算服务，但当前响应和链上证据还不足以确认它是否已经结算。

它不表示“尚未付款”，更不允许创建替代 Intent、授权、幂等键或随机数。

何时会进入该状态

控制面签发授权后，客户签名器生成准确的付款签名，Agent SDK 再发送付费请求。以下情况可能导致结算状态未知：

• 付费请求离开 Agent 运行时后超时；
• 连接在可靠响应返回前关闭；
• 资源响应缺少结算证据，或包含无法解析的结算证据；
• 结算服务、资源服务器、RPC 服务或链暂时提供不完整或互相冲突的证据。

此时付款可能已经成功，但 Agent 没有收到资源响应。

恢复步骤

1. 保存 SettlementUnknownError 中的 intentId 和 authorizationId。
2. 停止该业务购买的自动付款重试，不要轮换幂等键。
3. 使用 agent.getPayment(intentId) 或 management.payments.get(intentId) 查询原 Intent。
4. 订阅签名的 agent_payment.settlement.* 和 agent_payment.resource.* Webhook，并按事件 ID 去重。
5. 在原 Intent 得到明确结果前，让业务任务保持待处理或对账状态。
6. 状态超过运营时限仍然未知时，应升级人工调查，不能把告警转成自动重付。

Agent SDK 会通过错误对象提供关联标识：

import { SettlementUnknownError } from '@stableops/agent-sdk'

try {
  await agent.x402Fetch(resourceUrl, {
    idempotencyKey: 'research-task-284:market-report:v1',
  })
} catch (error) {
  if (error instanceof SettlementUnknownError) {
    await saveForReconciliation({
      intentId: error.intentId,
      authorizationId: error.authorizationId,
    })

    const payment = await agent.getPayment(error.intentId)
    console.error({
      intentId: payment.intentId,
      paymentStatus: payment.status,
      resourceStatus: payment.resourceStatus,
    })
  }

  throw error
}

查询记录是安全的。换一个幂等键调用 x402Fetch 发起新购买则不安全。

状态如何得到最终结果

StableOps 不会仅因墙上时钟超时就释放已经提交的预算。系统必须先确认授权已经过期且未使用，也不存在待确认的匹配转账。这条保守规则可以避免第一笔付款仍可能结算时，同一笔资金又被计为可用。

支付结果与资源结果彼此独立

即使支付结算已经明确，资源结果仍可能是 unknown 或 failed：

• settled 加 response_received 表示付款和付费 HTTP 交换都有可靠证据。
• settled 加 unknown 表示资金已经转移，但 Agent 可能没有收到资源。
• StableOps 确认链上状态为 settled 前，资源响应也可能已经返回。

资源交付问题应通过卖方的重放、支持或业务补偿流程解决。绝不能把资源缺失解释为付款没有发生。

相关内容

• Agent Payments Webhook
• 查询 Agent 支付
• 查询 Agent 支付回执
• 查询 Agent 支付状态迁移记录
• 为什么支付在等待审批？