# FailEcho

Live failure intelligence for autonomous software.

Use FailEcho when a tool, API, or MCP operation fails and you want to know
whether other autonomous systems recently experienced the same failure.

Before retrying blindly, query FailEcho for observed failure rates and
recovery outcomes. A retry that is failing for every other agent right now is
a retry you can skip.

FailEcho is not an error database, not an uptime monitor and not a debugger.
It is a shared, real-time, anonymous network keyed on:
service + operation + version + schema_hash + failure fingerprint.

## Endpoints

MCP:
https://failecho.com/mcp

OpenAPI:
https://failecho.com/openapi.json

Docs:
https://failecho.com/docs

## MCP tools (preferred for agents)

Streamable HTTP, stateless, no auth.

- check_tool_failure       ask what is happening with a failure, before retrying
- report_tool_failure      contribute a failure observation
- report_tool_success      contribute a success (failure rates need a denominator)
- report_recovery_outcome  report whether a recovery action worked

## REST API

- POST /v1/observe   report one tool-call outcome (success or failure)
- POST /v1/query     ask what FailEcho knows about a failure (stores nothing)
- POST /v1/outcome   report whether a recovery action worked
- GET  /v1/services  current status per service/operation
- GET  /v1/stats     network-wide counters, real and demo kept separate
- GET  /v1/recovery-intelligence  best evidenced recovery actions right now
- GET  /health       liveness

## Vocabulary

Failure Echo    a normalized observed failure, shared by fingerprint
Recovery Echo   evidence that a recovery action worked
Incident        a sudden abnormal failure increase
Reporter        an agent or runtime sending telemetry
Fingerprint     the canonical normalized error identity

## Status values

HEALTHY (failure rate < 5%), DEGRADED (< 30%), MAJOR (>= 30%),
INSUFFICIENT_DATA (fewer than 10 observations in the last hour).

## Confidence

Confidence is a Wilson score lower bound over observed recovery attempts,
capped below 1.0, discounted when fewer than 3 distinct reporters back it. It
is arithmetic, not a model output, and you can recompute it from the attempts
and successes returned alongside it. When evidence is insufficient the
recommendation is null. FailEcho never fabricates confidence.

## Privacy

Send failure metadata only: service, operation, version, schema_hash, outcome,
error_type, error_code, a short error message, latency.

Never send: prompts, model messages, tool arguments, tool results, request or
response bodies, HTTP headers, cookies, API keys, tokens, customer names,
emails, or any user content. Unknown fields are dropped before storage. Error
messages are normalized (identifiers replaced, credential-shaped substrings
redacted) and the raw text is discarded.

Reporter identity is optional. Supply X-Reporter-ID (REST) or reporter_id
(MCP) and it is salted and hashed on arrival; the raw value is never stored.
Anonymous reporting is fully supported.

## Cost

No account required.
No API key required.
Free during the public MVP.