結算狀態未知時應該怎麼辦？

停止付款重試，核對原 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-payments-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 支付狀態遷移記錄
• 為什麼支付在等待審批？