Failure handling

Errors and warnings

Failures use stable public codes; optional-source problems remain attached to successful partial results.

Query failures

A failure means the profile's required source could not produce a usable result. The public error contains a stable code, safe message, and optional source name. Internal exceptions are never exposed through the contract.

Handle stable error codesTypeScript

const result = await query(input);

if (!result.ok) {
  switch (result.error.code) {
    case "TIMEOUT":
      // The required source exceeded the query deadline.
      break;
    case "TARGET_BLOCKED":
      // The destination is not allowed by the public-address policy.
      break;
    default:
      // Handle other stable QueryErrorCode values.
  }
}

Failure categories

Category	Examples	Typical response
Input and target	Invalid host, port, mode, or blocked address	Correct the request; do not retry unchanged.
Discovery and connection	DNS failure or connection failure	Retry only when transient failure is plausible.
Deadline and cancellation	Timeout or caller abort	Respect caller intent and bounded retry policy.
Response integrity	Malformed or oversized response	Treat the source as unusable; do not parse around limits.
Internal	Unexpected implementation failure	Log safely outside the result and investigate.

Warnings and provenance

Warnings are non-fatal. They explain why partial is true and can point at a specific source. The source report remains the authoritative outcome for every attempted, skipped, blocked, or unsupported source.