Skip to main content
When a check does not find the token, the claim comes back with a diagnosis: a named code, the cause in one sentence, the fix in one sentence, and the evidence the probe matched on.
Twelve codes, each matching one specific shape of wrongness. The full catalogue is here.

​
The fields

​
string
required
A stable identifier. Branch on this — it will not be reworded. One of the thirteen in the catalogue.
​
string
required
One sentence saying what is actually true right now, with the real names and values in it. Render it; do not match on it.
​
string
required
One sentence saying what to change. For the cases where nothing needs changing — negative_cache — it says so and gives the wait.
​
object
required
The evidence the probe matched on, and its shape depends on code. record_at_apex carries { name, value }; servfail carries { resolvers }; negative_cache carries { secondsRemaining }.
observed is a tagged union keyed on code. Narrow on code before reading it — there is no field common to all thirteen.

​
Where a diagnosis comes from

The probes run over an observation that has already been collected — recursive resolvers first, then the authoritative nameservers if the answer was negative. No probe issues a query of its own, which is why a claim can carry a diagnosis without any extra DNS traffic when you read it back. See How verification works for the four steps.

​
Rendering one

The whole “what now” message for a pending claim is two fields:
A claim that is not proved always carries one or the other. diagnosis means something has to change; waitEstimate means nothing does.
cause and fix are product copy and are improved regularly. They are safe to render verbatim and unsafe to match on. If you need to key behaviour off a case, key it off code.

​
The three groups

The thirteen codes fall into three groups, and it is worth styling them differently:

You wrote it wrong

domain_appended, record_at_apex, value_formatted, record_on_www, no_matching_record, record_absent, cname_conflict, expired_tokenActionable now. Show fix as the primary action. expired_token is the cheapest of them: the record is already in the right place and only its value is stale.

Just wait

negative_cache, not_publishedNothing to do. Showing a fix here is the mistake this product exists to avoid.

Your provider is broken

servfail, lame_delegation, foreign_tokenReal problems, but not with the record. servfail is DNSSEC; lame_delegation is the delegation itself; foreign_token is another account.