closed loop error `20739` should not retry for melt quotes

[gudnuf]

Currently when a user tries to pay an not allowed invoice with a gift card, /v1/melt/quote/bolt11 returns error code 20739 and the app retries. This error should not be retried

[gudnuf]

@claude can you take care of this. Look how our app handle non-retryable errors in the mutations and identify where this error can surface and make sure its not retried

[claude]

Claude finished @gudnuf's task in 4m 53s —— View job • claude/issue-1089-20260519-1932 • Create PR ➔

---

Done

• Explore how the app handles non-retryable errors in mutations
• Find where Cashu error 20739 can surface (melt quote flow)
• Identify the specific mutation(s) that hit /v1/melt/quote/bolt11
• Make sure 20739 is treated as non-retryable
• Run bun run fix:all (biome + typecheck pass; 2 pre-existing vite-env.d.ts warnings unrelated to this change)
• Commit changes

Analysis

createMeltQuoteBolt11 (the /v1/melt/quote/bolt11 call) is invoked in exactly two places:

1. app/features/send/cashu-send-quote-service.ts:150 — used by the useCreateCashuLightningSendQuote mutation (app/features/send/cashu-send-quote-hooks.ts:122)
2. app/features/receive/receive-cashu-token-quote-service.ts:251 — used by the useCreateCrossAccountReceiveQuotes mutation (app/features/receive/receive-cashu-token-hooks.ts:284)

Both mutations' retry functions only short-circuited on DomainError, so any MintOperationError from the mint (including code 20739) fell through to failureCount < 1 and was retried once.

The codebase already has the right pattern in useInitiateCashuSendQuote (cashu-send-quote-hooks.ts:331-336) and useInitiateMelt (cashu-receive-quote-hooks.ts:704-709):

retry: (failureCount, error) => {
  if (error instanceof MintOperationError) {
    return false;
  }
  ...
}

A MintOperationError is a definitive numeric response from the mint — retrying won't change the answer. Transient connectivity surfaces as NetworkError instead, which is still retried.

Change

In both useCreateCashuLightningSendQuote and useCreateCrossAccountReceiveQuotes, added || error instanceof MintOperationError to the existing DomainError short-circuit, and imported MintOperationError in receive-cashu-token-hooks.ts (already imported in the send hook).

This blocks 20739 and every other mint error code from being retried for melt quote creation, matching the policy already used elsewhere for mint operations.

Branch: claude/issue-1089-20260519-1932 ·

[gudnuf]

@claude please audit that this is safe and that all mint op errors should not retry. Or if we should specifically not retry on the specified error code

[claude]

Claude finished @gudnuf's task in 3m 10s —— View job

---

Audit: is blocking all MintOperationError safe, or should we only block code 20739?

• Read the previous change and confirm the diff
• Find MintOperationError definition and where it can be thrown
• Enumerate Cashu mint error codes and reason about retryability
• Check existing precedent in useInitiateCashuSendQuote and useInitiateMelt
• Decide: blanket MintOperationError skip vs. code-specific (20739 only)
• Report findings

Verdict: blanket block is correct. Keep the change as-is.

What MintOperationError actually means

From node_modules/@cashu/cashu-ts/lib/types/index.d.ts:2356-2363:

/** Thrown when a protocol error (per NUT-00) occurs.
 *  See https://github.com/cashubtc/nuts/blob/main/error_codes.md */
export declare class MintOperationError extends HttpResponseError {
  code: number;
  constructor(code: number, detail: string);
}

Looking at the cashu-ts implementation: this class is only constructed when the mint returns a parseable Cashu error body { code, detail }. Three error classes exist with distinct semantics:

Error	When it surfaces	Should retry?
NetworkError	Connectivity (timeout, DNS, hung request)	✅ yes — transient
HttpResponseError	Non-2XX without a Cashu body (e.g. bare 500/502/503)	✅ yes — possibly transient
MintOperationError	Non-2XX with a Cashu-spec code+detail	❌ no — deterministic

Crucially, transient/infrastructure failures do not surface as MintOperationError. The mint had to deliberately decide on a numeric code and write it into the response body. That's a stateful decision the mint will repeat on retry.

Why blanket is safer than enumerating "20739 only"

1. 20739 is not in the NUT spec. Our app/lib/cashu/error-codes.ts enumerates the standard codes; 20739 isn't one of them — it's a custom code from a specific closed-loop/gift-card mint. Different mints will invent different custom codes. A "deny-list of bad codes" would be permanently stale.

2. No NUT code is meaningfully retryable on /v1/melt/quote/bolt11. Walking through what the mint can return when creating a melt quote:

   • 11005 UNIT_NOT_SUPPORTED — won't change
   • 11006 AMOUNT_OUT_OF_LIMITS — won't change for the same invoice
   • 20003 MINTING_DISABLED — admin state, won't flip in 1s
   • 20006 INVOICE_ALREADY_PAID — won't change
   • 20007 QUOTE_EXPIRED — won't change for the same invoice
   • 30001 / 31001 AUTH_REQUIRED — won't change without re-auth
   • 31003 / 31004 BAT limits — rate-limit-shaped, but TanStack's "retry once immediately" wouldn't help anyway; 429 handling lives separately at cashu-receive-quote-hooks.ts:388.
   • Custom codes (like 20739) — by definition we can't enumerate these.

3. Cost of an unnecessary retry is real. Each failed melt-quote retry is ~3s of latency + a duplicate POST to the mint. For non-retryable conditions the user just stares at a spinner before getting the error they were always going to get.

4. Cost of being wrong (blocking a code we should have retried) is near zero. If a transient-flavored code ever did show up, the user gets a normal error and taps the action again — same UX as the current "retry once" but a few seconds sooner. Compare to the alternative: shipping an allowlist that needs babysitting every time a mint adds a code.

5. Pattern consistency. Four existing mutations already use the blanket form:

   • useInitiateCashuSendQuote — cashu-send-quote-hooks.ts:332
   • useInitiateMelt — cashu-receive-quote-hooks.ts:705
   • spark-receive-quote-hooks.ts:599
   • (and cashu-receive-swap-service.ts:217 / cashu-receive-quote-service.ts:334 use MintOperationError to drive failureReason recovery paths)

   Diverging now would create a third "kinda non-retryable" category that's harder to reason about.

Nit on the existing code (optional, not part of this issue)

In all four mutations, failureCount < N is the only retry signal — there's no jittered backoff or 429-respecting Retry-After handling at the mutation layer. That's fine for the cases here (one immediate retry against NetworkError), but if rate-limit pressure on melt-quote creation becomes a real issue, the 429-aware pattern at cashu-receive-quote-hooks.ts:388 is the model to copy. Not blocking; just flagging for the future.

TL;DR

MintOperationError is, by construction, a deliberate protocol-level response from the mint with a stable code. Retrying it within a sub-second window has zero chance of changing the answer for the codes that can surface on /v1/melt/quote/bolt11. Blanket blocking matches the existing convention, doesn't require maintaining a code allowlist, and NetworkError/bare HttpResponseError still retry — so transient failures aren't affected.

The previous PR is safe and correct. No additional code changes needed.
• claude/issue-1089-20260519-1932