> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.next-dev.rtcleague.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.next-dev.rtcleague.com/_mcp/server.

# Errors

The TelEcho API returns errors as JSON with a stable envelope so your SDK
or client code can switch on `error.code`:

```json
{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The API key provided is invalid."
  }
}
```

## HTTP status codes

| Status | Meaning                                                                        |
| ------ | ------------------------------------------------------------------------------ |
| `200`  | Request succeeded                                                              |
| `201`  | Resource created (e.g. a call was started)                                     |
| `400`  | Bad request — invalid params, malformed body, missing required field           |
| `401`  | Authentication failed — missing, malformed, revoked, or expired API key        |
| `402`  | Payment required — your subscription is past due, cancelled, or out of minutes |
| `404`  | Resource not found, or not in your org                                         |
| `429`  | Rate limit exceeded ([details](/getting-started/rate-limits))                  |
| `5xx`  | TelEcho infrastructure issue — safe to retry with exponential backoff          |

## Error codes

### Authentication

| Code              | When                                                 |
| ----------------- | ---------------------------------------------------- |
| `missing_api_key` | No `Authorization` header sent.                      |
| `invalid_api_key` | Key has wrong format, doesn't exist, or was deleted. |
| `revoked_api_key` | Key was revoked from the dashboard.                  |
| `expired_api_key` | Key's `expires_at` is in the past.                   |

### Request validation

| Code             | When                                                       |
| ---------------- | ---------------------------------------------------------- |
| `invalid_id`     | A `tel_*_*` ID couldn't be parsed.                         |
| `invalid_target` | Both or neither of `agent_id`/`workflow_id` were provided. |
| `invalid_cursor` | The `cursor` parameter is malformed or stale.              |
| `invalid_date`   | A date filter isn't valid ISO 8601.                        |
| `invalid_filter` | A filter value isn't in the allowed enum.                  |

### Resource state

| Code                                                                | When                                                                  |
| ------------------------------------------------------------------- | --------------------------------------------------------------------- |
| `agent_not_found` / `workflow_not_found` / `phone_number_not_found` | Resource doesn't exist or belongs to another org.                     |
| `agent_inactive` / `workflow_inactive` / `phone_number_inactive`    | Resource exists but is in a non-active state.                         |
| `no_outbound_trunk`                                                 | The phone number isn't configured for outbound calling.               |
| `no_routing_target`                                                 | No agent or workflow attached to the phone number, and none provided. |

### Billing & telephony

| Code                                            | When                                                               |
| ----------------------------------------------- | ------------------------------------------------------------------ |
| `call_blocked`                                  | Subscription expired, cancelled, or out of minutes. Returns `402`. |
| `outbound_call_failed`                          | LiveKit / SIP error during outbound dial. Returns `502`.           |
| `rate_limit_per_minute` / `rate_limit_per_hour` | Exceeded your key's rate limit. Returns `429`.                     |

## Retry strategy

* **`429`** — wait for the time in the `Retry-After` header before retrying.
* **`5xx`** — exponential backoff: 1s, 2s, 4s, 8s … up to 30s.
* **`4xx` (other than 429)** — don't retry; fix the request.