# EchoRelay

> EchoRelay is a multi-tenant HTTP relay. A caller makes one authenticated POST to its EchoRelay endpoint; EchoRelay authenticates, validates, rate-limits, bills, and fans the request out to one or more downstream HTTP targets — with at-least-once delivery, automatic retries, and a dead-letter queue.

Use EchoRelay to decouple a caller from its downstream targets: send once, and EchoRelay reliably delivers to every configured destination. A request is accepted immediately (`HTTP 202`) and delivered asynchronously.

## Integration

- [Full integration guide](https://docs.echorelay.dev/llms-full.txt): complete reference — endpoint URL, authentication, request and response formats, error codes, fan-out, delivery guarantees, and worked examples.
- [Docs site](https://docs.echorelay.dev): MCP, REST, project-key lifecycle.
- [REST API reference](https://docs.echorelay.dev/rest) — programmatic project management at `api.echorelay.dev`.
- [MCP guide](https://docs.echorelay.dev/mcp) — connect Claude / Cursor / any MCP client.

## Quick reference (data plane)

- **Endpoint URL:** `https://{tenant}.echorelay.cloud/{line}/{endpoint}`
- **Auth:** `Authorization: Bearer <api-key>` header (project-level keys — one key works on every endpoint in the project)
- **Modes:** `live` keys debit paid credits; `test` keys debit the testing pool (250 RPM cap)
- **Success:** `202` with `{"status":"queued", ...}`
- **Grace:** within 24h of `expiresAt`, requests still succeed and add `X-Echorelay-Key-Status: expired_grace`
- **Errors:** `402` out of credits · `429` rate-limited · `401 key_revoked` / `401 key_expired` (once you've held a valid key) · `404` for unknown tenant / line / endpoint / key

## Errors & remediation

Every rejection names a machine-readable `error`/`reason` and the one action that clears it. Over MCP, the named tool *is* the fix — each error points at the tool to call.

| Status | `error` | Cause | Fix |
|---|---|---|---|
| `402` | `insufficient_credits` | Paid / prepaid pool is empty | `start_topup` (buy credits) or `change_plan` (a subscription with an included monthly allowance) |
| `402` | `testing_credits_exhausted` | Testing pool is empty | `start_topup` / buy a credit pack |
| `429` | `rate_limit_exceeded` | Over your steady RPM. The body carries `limit`, `tier`, `retryAfterSeconds` and the response sets a `Retry-After` header | wait `Retry-After`, then raise steady RPM: `change_plan` or `subscribe_addon rpm_*` (free tier → upgrade with `change_plan`) |
| `401` | `key_revoked` / `key_expired` | The key you presented was valid but is now revoked, or past its 24h post-expiry grace | mint a fresh key with `create_api_key`; inspect `get_key_policy` / `reveal_rotation_successor` |
| `404` | *(opaque on the wire — never reveals whether a tenant exists)* | unknown tenant / line / endpoint / key, failed IP allowlist, or attribute validation | diagnose on the authenticated side: `dry_run_endpoint` (validation), `get_request` (why one specific past request was rejected), `get_config` / `list_endpoints` (routing), `get_billing` (pools, tier, RPM) |

`get_billing` is the state oracle: current tier, live RPM (plus the free-tier decay countdown), and every credit pool in one call — check it first when a `402` or `429` is unexpected.

## Quick reference (management)

- **REST:** `https://api.echorelay.dev` — Bearer-authed JSON, project implicit from token
- **MCP:** `https://mcp.echorelay.dev` — JSON-RPC, same tools as REST
- **Panel:** `https://echorelay.dev` — human-facing customer panel