[NormandErwan]

Problem

ci fails intermittently on main (after #18, #20, #21, #24) and PR runs need re-runs. UnityPackage_BuildTest_Success runs the test command, which HEADs every xref href on docs.unity3d.com; the site answers 429 TooManyRequests, so valid links are reported invalid.

#24 is not the cause: it only touches the Deploy pages step of unity-xref-maps.yml.

Change

Utils.TestUriExists:

Case	Behavior
429 or 503	Retry, up to --maxAttempts requests in total
Delay	Retry-After (delta or date) if present, else exponential backoff 1, 2, 4… s; capped at 60 s (no overflow at high attempt counts)
Still 429/503 after the last attempt	Reported invalid, as before
Retries	Not logged: CommandTests assert zero log records

test command: new --maxAttempts option, default 5 (Constants.DefaultMaxAttempts), values below 1 rejected.

CommandTests pass --maxAttempts 8 (TestMaxAttempts, up to 123 s of backoff per link): with the default 5, CI on 06f4651 still had 2 links at 429 on GitHub runners. They still check real URLs (the HTTP-mocking approach was reverted in 8a62bb1).

New UtilsTests: a local HttpListener answers 429 (Retry-After: 0) twice, then 200; checks result and request count for maxAttempts 2 and 3.

README documents retries and --maxAttempts.

Verification

• dotnet build -c Release: 0 warnings.
• dotnet test -c Release with TestMaxAttempts: 13/13 on 2 full runs; 1 earlier run had 1 failure whose output was not captured (no TooManyRequests in it).
• UtilsTests fail (2/2) with retries disabled, pass with them.
• Backoff for attempts 1–40: 1, 2, 4, 8, 16, 32, then 60 s.
• test command against a local server:

Args	Result
default	429×2 then 200: valid after 3 requests; always 429: 5 requests (~15 s), then invalid
--maxAttempts 2	2 requests each, both invalid
--maxAttempts 0	Rejected: --maxAttempts must be at least 1.

Not verified: whether docs.unity3d.com sends Retry-After with its 429 — 620 HEAD requests from a non-GitHub IP never triggered a 429. The code falls back to exponential backoff when the header is absent.

🤖 Generated with Claude Code

https://claude.ai/code/session_015PW29oEyQ3Jh7amkT1sjAi

[NormandErwan]

ci / build failed on 06f4651: UnityPackage_BuildTest_Success still reports 2 InputSystem links as TooManyRequests after 5 attempts (~15 s of backoff). Before this PR the same test failed on dozens of links, so retries help, but docs.unity3d.com keeps rate-limiting GitHub runners longer than the default budget.

This is this PR's to fix: the retry budget is too small. Waiting on a decision on how to raise it (higher default --maxAttempts, or pacing requests) before pushing.

---

Generated by Claude Code