Errors | TelEcho API Reference

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

1 {
2   "error": {
3     "type": "authentication_error",
4     "code": "invalid_api_key",
5     "message": "The API key provided is invalid."
6   }
7 }

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)
`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.