Error Handling

Error Categories#

The app may encounter several classes of errors when fetching or interpreting the server‑declared Awareness document:

• Network errors — timeouts, unreachable hosts, captive portals, or protocol failures.
• Transport errors — TLS handshake failures, protocol downgrades, or QUIC fallback.
• Response errors — invalid JSON, missing fields, or unexpected structures.
• Cache errors — expired or missing cached values.
• Runtime errors — interruptions during fetch or merge operations.

Each category is handled independently to maintain clarity and predictability.

Network Errors#

When the app cannot reach the Awareness endpoint:

• Retain the most recent cached server state.
• Do not attempt retries beyond the platform’s default behavior.
• Treat the server state as Unknown if no cached value exists.
• Allow the merge logic to proceed using local signals.

This ensures that temporary outages do not cause oscillation or user confusion.

Response Errors#

If the server returns a malformed or incomplete response:

• Ignore the response entirely.
• Preserve the previous cached value.
• Treat the server state as Unknown if no valid cache exists.
• Do not attempt to infer missing fields.

The app never attempts to repair or interpret invalid data.

Cache Errors#

If the cached server state is missing or expired:

• Treat the server state as Unknown.
• Allow the merge logic to treat Unknown as Stable.
• Attempt to refresh the server state on the next safe opportunity.

This behavior ensures that the app remains functional even after long offline periods.

Merge‑Layer Errors#

If an error occurs during the merge process:

• Default to the most conservative state: Drift.
• Log the event internally (platform‑native logging only).
• Continue normal operation on the next evaluation cycle.

This prevents silent failures and ensures that the indicator never displays misleading clarity.

UI Behavior During Errors#

The Awareness indicator must remain stable and predictable:

• Never flash or oscillate due to transient errors.
• Never display partial or intermediate states.
• Use the last known valid Awareness state until the next successful merge.

The UI reflects the model’s stability guarantees.

Forward Compatibility#

The error‑handling model is designed to support future versions of the Awareness endpoint:

• Unknown fields are ignored.
• Missing fields trigger fallback behavior.
• Additional metadata does not affect v1 behavior.

This ensures that the RTT‑App remains compatible as the RTT ecosystem evolves.