Responses & errors

What successful unlocks and payment-required failures look like.

Success — HTTP 200

json

{
  "ok": true,
  "status": 200,
  "settlement": {
    "txHash": "0x…",
    "payer": "0x…",
    "amountWei": "…",
    "amountUsdc": "0.01",
    "paymentId": "0x…",
    "blockNumber": 123,
    "verifiedAt": "…"
  },
  "result": { "text": "…" },
  "meta": {
    "requestId": "…",
    "service": "quick-brief",
    "mock": false,
    "demo": false
  }
}

Payment required — HTTP 402

Missing or invalid payment returns a structured error.payment object: gateway, seller, feeWei, feeUsdc, rpcUrl, unlockPath, auth type — plus x402 headers. Agents should follow that object rather than HTML.

Other codes

Paused or missing service
Amount mismatch / wrong seller
Replayed transaction
Invalid signature
Rate limited
DURABLE_STORE_REQUIRED — production unlocks need Supabase
UPSTREAM_FAILED with creditIssued: true — paid but the reply failed; one free re-unlock on the same payment confirmation within 24h (no second deposit)
UNLOCK_CREDIT_INVALID — credit missing, expired, or already used

Machine codes live in the gateway error union (e.g. SERVICE_PAUSED, TX_ALREADY_CONSUMED).

Paid-failure unlock credit

After a verified payment is marked spent, if fulfillment fails the gateway stores a one-time unlock credit keyed by the payment confirmation. Agents retry POST /api/gateway with the same payment headers and a fresh EIP-191 signature over the new input — settlement is not charged again.