Degraded retrieval

An anti-hallucination product must never present an ungrounded answer as a grounded one. When grounding was requested and produced nothing, or produced less than it should have, the response says so in docketrouter.degraded and the model is told the same thing in its prompt.

This is the field to watch in production. It is the difference between "we looked and there is no authority on this" and "we could not look", and between either of those and a normal answer.

The shape

docketrouter.degraded

null                              // the normal case: retrieval worked

{ "retrieval": true,              // nothing was retrieved at all
  "index_unreachable": false,
  "reason": "no authority matched this query" }

{ "retrieval": false,             // the primary index was down, fallbacks produced something
  "index_unreachable": true,
  "reason": "the primary research index did not respond; results came from fallback sources and may be incomplete" }

{ "retrieval": true,              // both: the index was down and nothing came back
  "index_unreachable": true,
  "reason": "the research index did not respond and no fallback authority matched" }

Field	Means
`retrieval`	No rule excerpt and no case came back. The answer is the model on its own, with no retrieved authority in the prompt.
`index_unreachable`	The primary fused index did not respond: a timeout or an error from the index. This is an outage, not a result.
`reason`	A sentence you can show a user directly. It is written to be read, not parsed.

Two failures that look identical from outside

Collapsing them is how a retrieval outage silently becomes "we looked and found nothing". A no-match is information about the question. An outage is information about us. index_unreachable is what tells them apart, and your interface should not say the same thing in both cases.

What the model is told

The degradation is not just reported to you. It is appended to the system prompt so the answer itself carries the caveat, whether or not your client reads the metadata.

when nothing was retrieved

RETRIEVAL DEGRADED: no authority matched this query. You have NO retrieved authority for
this request. Answer from your own knowledge, state plainly at the top of your answer that
no authority could be retrieved and the answer is therefore unverified, and do not imply
anything below was checked against a source.

when the index was down but fallbacks produced something

RETRIEVAL DEGRADED: the primary research index did not respond; results came from fallback
sources and may be incomplete. Rely only on what is actually shown below, and say plainly in
your answer that the research index was unavailable so the authority set may be incomplete.

When it fires, and when it cannot

Request	Degraded
Default request, retrieval works	`null`
Default request, no rule and no case matched	`retrieval: true`
Default request, fused index unreachable but a fallback produced a case	`index_unreachable: true`, `retrieval: false`
`rules: false`, `cases: true`, nothing matched	`retrieval: true`
`rules: false` and `cases: false`	Always `null`. Nothing was asked for, so nothing can be missing.
`juice: false`	Always `null`. The grounding layer did not run.

A null degraded on an ungrounded request is not a promise

If you turn grounding off, degraded is null because there is nothing to degrade, not because the answer is grounded. Gate on juiced as well when you render a grounding badge.

What it obliges you to show

This is a product requirement, not a suggestion.

A grounded-research interface makes an implicit promise: the citations and the reasoning are backed by retrieved authority. When degraded is set, that promise is false for this answer, and the interface has to say so before the user acts on it.

Show a persistent caveat, not a toast. The banner should still be on screen when the user copies the answer into a brief.
Do not render an empty sources panel as though it were a full one. A sources panel showing zero results next to a confident answer reads as "no authority needed", which is the opposite of the truth.
Distinguish the two reasons in your copy. "No authority in our index matched this question" invites the user to rephrase. "Our research index was unavailable" invites them to retry, and tells them the problem is ours.
Retry on an outage, not on a no-match. index_unreachable: true is transient and worth one retry with backoff. retrieval: true with a reachable index will produce the same empty result every time.
Alert on the rate, not on the event. A single degraded response is normal. A rising share of them across a day is an incident, and your usage log has the raw material: sources_n is 0 on every degraded request.

Detecting it

TypeScript

const dr = data.docketrouter;

if (dr.degraded) {
  const transient = dr.degraded.index_unreachable;
  banner({
    tone: "amber",
    text: transient
      ? "Our research index was unavailable, so the authority set for this answer may be incomplete."
      : "No authority in our index matched this question. This answer is the model's own knowledge and was not grounded.",
    retryable: transient,
  });
}

// The grounding badge needs both signals, not one.
const grounded = dr.juiced && !dr.degraded && (dr.sources?.rules.length || dr.sources?.cases.length);

On a streamed response, degraded arrives in the first chunk with the rest of the grounding metadata, before any text. You can render the banner before the first token lands. See Streaming.

Testing it

The no-match branch is easy to reproduce on demand, which makes it easy to build against. Ask something with no legal content and turn off rule retrieval so nothing scores:

forcing a degraded response

curl https://docketrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer dr-…" -H "content-type: application/json" \
  -d '{ "model": "deepseek/deepseek-v4-flash", "max_tokens": 400,
        "messages": [{ "role": "user", "content": "zzqqxx wibblefrotz nurglespang 88811 quorplenix" }],
        "docketrouter": { "rules": false, "cases": true, "verify": false } }'

# "degraded": { "retrieval": true, "index_unreachable": false,
#               "reason": "no authority matched this query" }

Put that call in your test suite. The degraded path is the one your users will hit at the worst moment, and it is the one least likely to be exercised by hand.

Something here wrong or missing? Mail hello@docketrouter.ai with the request_id and we will fix the docs or the API, whichever is broken.