The user asks one question; the system answers several

When someone asks whether a domain is available, they may mean that the registry has no current record, that a registrar will offer the name, that the name is not premium-priced, that it can be purchased in their jurisdiction, or that using it will not create a legal conflict. Those are different claims with different sources.

A registry RDAP response is useful evidence about registration state at a point in time. It does not quote the registrar checkout, reserve the name, establish price, or clear trademark and common-law risk. The honest interface therefore reports the bounded claim it can support.

  • Registered: a direct registry source returned a decisive current record.
  • Likely unregistered: a calibrated registry lookup returned not-found.
  • Unknown: the provider timed out, rate-limited, conflicted, failed calibration, or could not support the TLD.
  • Manual: current registrar price, purchasability, and legal use still require another action.

Why a 404 is not enough

HTTP 404 can mean that the queried domain has no registry record. It can also mean the endpoint is wrong, the provider does not correctly support that registry, or an aggregator has returned a generic absence for a name it never resolved. Treating every 404 as free creates the most dangerous failure mode: a confident false positive.

NamingSignal pairs absence with a known-registered canary for the same TLD. Before trusting not-found for a candidate, the provider must successfully recognize a domain that is known to exist. If the canary fails, the candidate stays unknown even when the candidate request returned 404.

The github.io false-free regression

During live validation, a generic RDAP path returned not-found for github.io even though the domain is registered and active. That observation became a permanent regression fixture. The point is not that every generic service is always wrong; it is that a checker must prove it can recognize a positive case before absence is allowed to influence a purchase decision.

The current implementation rejects generic rdap.org bootstrap endpoints as registry fallbacks, discovers authoritative services from IANA data, caches calibration separately from candidate evidence, and keeps failed or missing canaries out of the available bucket.

A safer reproducible test

For each TLD and provider, run a known-registered canary and a high-entropy candidate through the same endpoint family. Record the exact URL, response status, source, check time, provider identity, and error state. Repeat after timeouts or provider changes instead of recycling an old green answer.

  • A positive record is confirmed registration evidence and does not need an availability canary.
  • A candidate not-found becomes only a likely-unregistered inference, and only while calibration is healthy.
  • HTTP 429, network error, timeout, malformed response, unsupported TLD, or a failed known-positive test remains unknown.
  • The final workflow opens the exact candidate at a registrar so the user can inspect price, premium status, term, fees, and current registrability.

What an API should return

A useful domain availability API returns more than available: true. An agent needs the observation state, source URL, provider, timestamp, confidence, and a human-readable detail explaining why the result is confirmed, inferred, unknown, or manual.

This structure also makes corrections possible. A stale or contradictory observation can be replaced without pretending the earlier result was timeless. Consumers can set their own risk policy. For example, they may accept likely-unregistered candidates during ideation but require a current registrar check before launch.

Corrections and limitations

This article describes the production policy and tested failure cases; it is not a claim that every TLD or registrar behaves identically. Provider behavior, bootstrap data, registration state, and price can change. NamingSignal preserves timestamps, rechecks stale evidence conservatively, and welcomes reproducible corrections with the source, candidate, time, and response details needed to investigate.