← Back to blog

Why "we don't know" is not "it never expires" in our free domain checker

2026-11-09

engineeringdomain

The free domain expiry checker takes one domain and returns two things: whether it resolves, and when its registration expires. The first part is easy. Most of the code is in the second, because "we have no expiry date" can mean four different things, and only one of them is a fact about your domain's registry.

If the tool merged them into one message, it would tell a .de owner their registry is silent when we never reached it, tell someone to retry a lookup that can never succeed, or call an unregistered name a failure. So the API gives each case its own response field, and the page shows a different sentence for each.

Where the date comes from

The expiry comes from RDAP, the registries' structured replacement for WHOIS. The lookup sends a request to https://rdap.org/domain/<name>. rdap.org is a bootstrap service that redirects to the RDAP server of the registry for that TLD. We read the expiration event and the registrar's name from the registry's JSON. There is no WHOIS client and no other fallback. If RDAP can't give us a date, we don't show one.

What you type is first reduced to the registrable domain using the public suffix list. www.blog.example.co.uk has no registration of its own; example.co.uk does. DNS is still checked against the exact hostname you typed, and the response returns both names as domain and queried. A working lookup for our own domain returns this:

{"domain":"okokumo.com","queried":"okokumo.com","resolves":true,"addresses":1,
 "expiry_known":true,"expires_at":"2027-07-18T14:39:27Z",
 "days_until_expiry":251,"registrar":"Scaleway SAS","latency_ms":93}

expires_at and days_until_expiry appear only when expiry_known is true. A domain that expires today has days_until_expiry: 0, which is a real answer, so when there's no date the field is left out instead of being sent as a 0 or -1 that could be mistaken for one. The other four outcomes all have expiry_known: false, and a separate flag says which one you got. The examples for outcomes 1, 2 and 4 are live responses.

1. The domain is not registered

{"domain":"nonexistent-zzz-9182734.com","queried":"nonexistent-zzz-9182734.com",
 "resolves":false,"addresses":0,"expiry_known":false,
 "expiry_no_registration":true,"latency_ms":84}

The registry answered that it holds no record for this name. That's an answer, not a failure, so no failure flag is set. The page says: "This domain is not registered — the registry holds no record for it, so there is nothing to expire."

2. The registry publishes no expiry date

{"domain":"sidn.nl","queried":"sidn.nl","resolves":true,"addresses":2,
 "expiry_known":false,"latency_ms":233}

No flag is set. The lookup succeeded, and the registry's record has no expiration event. .nl is an example: SIDN's RDAP server returns registrations without an expiry date. This is the only case where the tool says, as a fact, that the registry publishes no date, because it's the only case where the registry told us so.

3. We couldn't read the registry's answer this time

{"domain":"example.nl", …, "expiry_known":false,"expiry_lookup_failed":true, …}

We can't trigger this one on demand, so the example is the shape from the test suite. Causes include a rate limit, a registry 5xx error, a malformed body, a body over 64 KB, or one of our own guards refusing a redirect. The upstream error is never passed on to the caller. The page says: "We could not read the registry's answer for this domain, so we do not know when it expires. Try again in a moment." This is the only message that suggests a retry, because it's the only case where a retry can help. In a live check, bbc.co.uk once returned this and gave a full date on the next try.

4. The TLD has no public RDAP service

{"domain":"google.de","queried":"google.de","resolves":true,"addresses":2,
 "expiry_known":false,"expiry_lookup_failed":true,
 "expiry_unsupported_tld":true,"latency_ms":24}

Some registries run no public RDAP server for rdap.org to redirect to. Our live checks found this for .de, .ch, .it, .es, .pt and .jp. The code has no hardcoded list. It detects the case at lookup time, as described below, so any other TLD in the same position gets the same answer. The page says the condition is permanent and that your registrar can still tell you the date. .fr, in case you wondered, publishes expiry dates without trouble.

This flag always comes together with expiry_lookup_failed, so the page checks the permanent flag first. If it checked the other one first, every .de visitor would be told to retry. The order is defined in a small, tested function, because when it lived in the component, swapping the two branches didn't fail a single test.

Telling 1 and 4 apart

Both reach us as the same bare 404 with the same body, because rdap.org returns its own "No RDAP service is available" document either way. The only difference is which server sent the 404:

google.de                   -> 404 from rdap.org            (no RDAP service)
nonexistent-zzz-9182734.com -> 404 from rdap.verisign.com   (not registered)

The classifier checks the host of the final request after redirects. A 404 from rdap.org itself means we were never redirected, so the TLD has no RDAP service. A 404 from any other host means a registry answered and has no record. If it can't tell which server answered, it reports a failed lookup, outcome 3, rather than guess.

Guards on a redirect we didn't choose

The free tool follows rdap.org's redirect to a registry server we didn't pick, for any name anyone can type, so its HTTP client is stricter than the default:

  • HTTPS only. A redirect to an http:// URL is refused.
  • A short chain. It stops once five requests have been made, so it follows at most four redirects. A normal referral takes one.
  • No private addresses. The client uses the same dial guard as the TLS checker, which refuses loopback and internal addresses at connect time, after DNS resolution.
  • Bounded time and size. DNS and RDAP share one 10-second budget, and at most 64 KB of the response body is read.

The name you typed needs a guard too. This tool never connects to your domain, so on its own, resolves: true would let an anonymous visitor use our resolver to test whether an internal hostname exists in someone's split-horizon DNS. If any resolved address is private, even one among several public ones, the request is refused with a 400: "That hostname resolves to a private address, so there is nothing public to check."

The endpoint is GET /public/domain-check. It allows 6 requests per minute per IP, sets Cache-Control: no-store, and stores nothing.

How it relates to the paid domain check

The free tool and scheduled domain monitoring call the same function, FetchRDAPExpiry. They share the rdap.org source, the parsing, the 64 KB cap and the 404 classification, so the two can't report different dates for the same domain. The free tool adds the stricter client described above. As the certificate expiry post explains, the scheduled check is up or down based on DNS resolution, alerts at D-30, D-14, D-7 and D-1 when the expiry is known, and never fails because of an RDAP error alone.

That's also why the checker shows its "Get an alert before this domain expires" link only when the expiry is known or the lookup failed temporarily. For an unregistered name, a TLD without RDAP, or a registry that publishes no date, the scheduled check would get no date from the same lookup, so we don't promise an expiry alert there. A .de domain can still be monitored for DNS resolution.


Try it on your own domains: the domain expiry checker is one of the free tools. No account, nothing stored.

Try the free tool: Domain expiry checker