Operate
When the data is degraded or stale
What each degradation signal means, what to do about it, and the one remedy that is never available.
Degradation is a normal operating state, not an incident. It has a defined shape, it is always disclosed, and it always resolves toward holding rather than crediting.
The signals
| Signal | Where it appears | What it means |
|---|---|---|
Foreshock-Coverage-Health: degraded | Response header on the screening and decision endpoints | At least one authority in scope for that request is not observable, or is outside its lag or verification thresholds. |
observable: false | coverage_health entry | That authority is not currently observable to us. |
verified_at outside its window | coverage_health entry | That authority’s registry entry has not been re-verified in time. |
Abnormal collector_lag_s | coverage_health entry | Our view of that authority is behind chain state. |
coverage.health_changed | Webhook | One of the above changed. This is the blind-spot notification. |
stage: STALE | exposure.revoked webhook | The data behind a match can no longer be trusted. |
What to do with each degradation reason code
All six produce HOLD with HTTP 200. The verdict is already correct; what varies is what clears it.
| Code | What clears it | What you do meanwhile |
|---|---|---|
SCREENING_DEGRADED | The screening source recovers. | Hold. Re-decide after recovery. |
BUDGET_EXHAUSTED | The budget period rolls, or you raise it deliberately. | Hold. See budget exhaustion. |
LIST_STALE | A fresher list lands. | Hold. Escalate if it persists across periods. |
REGISTRY_ENTRY_STALE | The registry entry is re-verified. | Hold. |
COVERAGE_BLIND_SPOT | The authority becomes observable again. | Hold. Record which scope was blind, and for how long. |
DECISION_TIMEOUT | The next call completes in budget. | Hold. Re-decide. |
RE_DECIDE_AFTER_RECOVERY appears in required_actions for exactly this: call the decision endpoint again once the degradation clears, with a new idempotency key. Do not credit on the strength of the earlier attempt.
Reading the header correctly
Foreshock-Coverage-Health is a pointer, not a report. On degraded, call GET /v1/coverage for the per-authority detail, then decide whether the affected scope matters for the deposit in front of you.
A degraded header does not invalidate the verdict you just received. The verdict stands. What the header tells you is that it was reached with reduced visibility, which is information your reviewers need and your post-incident timeline will want.
Falling back to something more conservative
“More conservative” needs a definition before you need it, not during. Write it down in advance:
- which asset and chain scopes you will stop crediting entirely while their authority is unobservable
- which amount threshold drops while coverage is degraded
- who is paged, and after how long a degradation persists
- what you tell the affected user, and when
A fallback policy invented during an incident is a fallback policy negotiated under pressure by whoever is awake.
The remedy that does not exist
There is no configuration, plan, parameter, or support request that converts a degraded input into a CREDIT. There is no reason code that permits a credit on degradation, and none will be added.
If holding through degradations is producing an unacceptable queue, the fixable variables are on your side or in the registry — the scope you registered, the thresholds you set, the review capacity you staffed. Widening a threshold to clear a backlog is not a fix; it is the failure the gate exists to prevent, applied deliberately.