Retry transient NFT download failures instead of persisting them for good

[jlobue10]

Fixes #3058

Problem

The NFT media cache persists every failed download as an ERROR sidecar and, apart from timeouts (retried once per session) and aborts, never fetches that URL again. That is the right call for a resource that is gone (404), but two conditions that clear on their own were being recorded the same way, and each of them leaves the NFT on "Preview is not available" in every later session until the whole cache is cleared:

1. HTTP error: 504 — nftstorage.link was down for weeks and answered 504 for everything. It is back now as a redirector to ipfs.io (the reporter's URL resolves and hashes correctly), but any GUI that recorded the 504 keeps throwing it from the sidecar without ever re-requesting the file. That is why the reporter sees cacheAPI:getChecksum: HTTP error: 504 for a URL that curl fetches in under a second.
2. net::ERR_BLOCKED_BY_RESPONSE — ipfs.io (which nftstorage.link now redirects to, and which the ipfs:// gateway option uses) sits behind Cloudflare bot management and intermittently answers Electron's net.request with a 403 "Just a moment..." challenge page (cf-mitigated: challenge). The GUI cannot solve a JS challenge, so the file fails, and the very next request usually succeeds. That page carries Cross-Origin-Resource-Policy: same-origin, which Chromium turns into ERR_BLOCKED_BY_RESPONSE when the request has an initiator and into a plain HTTP 403 otherwise; both were persisted as permanent failures.

I could not confirm the race in NFTPreview suggested in the issue: getURI and getChecksum share the same fetchRemoteContent promise for a URL (ongoingRequests), so the optimistic tile waits for the same download the verifier runs and cannot observe a different outcome for the same URI.

Fix

isTransientDownloadError classifies timeouts, HTTP 5xx, 403/408/425/429 and net::ERR_* failures as transient. CacheManager retries a persisted transient failure once per session (as it already did for timeouts) and again whenever TRANSIENT_ERROR_RETRY_DELAY (10 minutes) has elapsed since the failure was recorded, so a gateway hiccup no longer blanks an NFT until the GUI restarts. Missing resources (404/410) and the size cap keep their settled behaviour; the IpfsGatewayDisabledError path is untouched (it was never persisted).

The retry decision uses the sidecar's existing timestamp, so already-poisoned caches recover on their own after upgrading: the next visit to the NFT re-requests the file.

Verification

• Reproduced the gateway behaviour with a standalone Electron 39 and Electron 43.4.0 (the version 2.7.4 ships) probe using the reporter's URLs: the redirect from nftstorage.link to ipfs.io is followed fine, but ipfs.io answered a burst of requests with the Cloudflare challenge (HTTP 403, cf-mitigated: challenge, CORP same-origin) before letting the same requests through minutes later. A local server returning the challenge page's headers reproduces net::ERR_BLOCKED_BY_RESPONSE on both Electron versions whenever the request carries an initiator.
• Local cache on this machine: 445 sidecars still hold HTTP error: 504 for nftstorage.link URLs recorded while the host was down, plus 12 × HTTP error: 403 from the same host.
• New unit tests: the classifier table, no retry within the delay, retry in a later session for 504 / 403 / ERR_BLOCKED_BY_RESPONSE, retry within the session once the delay has elapsed, and a 404 staying settled across sessions.
• packages/gui jest: 396/396. eslint and prettier clean; no new tsc errors in the touched files.

🤖 Generated with Claude Code

---

Note

Low Risk
Changes are confined to Electron NFT download caching and retry policy; permanent-error and IPFS-gateway-disabled paths are unchanged.

Overview
NFT media cache errors from gateway outages, Cloudflare challenges, rate limits, and similar transient failures no longer stay poisoned until the user clears the whole cache.

isTransientDownloadError (in downloadFile) now classifies timeouts, HTTP 5xx, selected 4xx (403/408/425/429), and net::ERR_* as retriable; 404/410 and size-cap errors remain permanent. CacheManager uses that helper instead of timeout-only checks, tracks session failures in transientFailureUrls, and exposes a 10-minute TRANSIENT_ERROR_RETRY_DELAY: persisted transient ERROR sidecars are retried once per new session and again in-session once the sidecar timestamp is older than the delay. Immediate repeat fetches in the same session still do not hammer the host.

Unit tests cover the classifier, no immediate retry for a fresh 504, cross-session retry for 504/403/ERR_BLOCKED_BY_RESPONSE, in-session retry after the delay, and 404 staying settled.

^{Reviewed by Cursor Bugbot for commit 3e4b097. Bugbot is set up for automated code reviews on this repo. Configure here.}

[danieljperry]

@cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit a3b8bcc. Configure here.}

[emlowe]

ckise and reooen for base branch change

[emlowe]

@jlobue10 can you retarget this to release/2.7.4 branch - I can't do it the easy way here through the PR as it pulls in a bunch of unrelated localization changes.

[jlobue10]

@jlobue10 can you retarget this to release/2.7.4 branch - I can't do it the easy way here through the PR as it pulls in a bunch of unrelated localization changes.

Will do

[emlowe]

bugbot review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit 3e4b097. Configure here.}