My short-link stats API learned that 'is it dead?' is a different question than 'is it alive?'

Description and use

The short‑link stats API now distinguishes three states—alive‑and‑clicked, alive‑and‑silent, and gone—eliminating ambiguity and improving performance.

Problem

The API returned 404 for both deleted links and links with zero clicks, making it impossible for callers to distinguish between a dead link and an alive but unused link.

Outcome

The API now clearly distinguishes between alive‑and‑silent, alive‑and‑clicked, and gone links, preventing downstream retry loops, alerts, and dead‑letter queues from misinterpreting 404s as successful responses. Performance improved from O(n) to O(1) for click window calculations.

Workflow

• 1. Detect link existence and return 404 for deleted or expired links.
• 2. Return stats with last_click_at null for alive links that have never been clicked.
• 3. Return stats with last_click_at timestamp for links that have been clicked.
• 4. Use per‑link counters to compute 30‑day click windows in O(1).

Evidence

A link with zero clicks and a link that was deleted look identical if you only check existence.

Source

So I split the contract. last_click_at: null now means "alive, never clicked." A 404 means "gone or expired."

Source

With per-link counters incremented on write, the stats call went from O(n) to O(1) and stopped timing out under burst traffic.

Source