Meeting API Errors

Meeting endpoints return failures as a non-2xx status with a single error object — branch on error.code and use error.message for diagnostics:

{
  "error": {
    "code": "not_found",
    "message": "meeting session not found"
  }
}

Authentication, permission, rate-limit, and other request failures that occur before reaching the Meeting service use the general API error codes with the standard plural envelope — a missing or invalid API key, for example, returns 401 with {"errors": [{"code": "10009", ...}]}, not the single-error shape below. Authenticated operations can also return 403, 429 (with Retry-After when authentication is overloaded), or 503. A small number of gateway-level failures (such as a 502 for a meeting URL the provider rejects outright) return a plain-text body with no JSON envelope at all, so parse error responses defensively.

Meeting Error Codes

Code	HTTP	Title	Detail	Action
`unauthorized`	`401`	Invalid or missing credentials	Service-level authentication failure. In practice the gateway rejects a missing or invalid key first with the general `10009` error, so this code is rarely seen.	Send your Telnyx API key as a bearer token in the `Authorization` header (exact `Bearer` capitalization).
`not_found`	`404`	Meeting session not found	No session with the supplied id belongs to the authenticated account.	Verify the session id and that it was created by the same account.
`invalid_request`	`400`, `413`	Request rejected	A field in the request is invalid or not allowed, for example a disabled `webhook_url`. A request that exceeds a documented size limit returns the same code with `413`.	Correct the field named in `message` and retry.
`invalid_state`	`409`	Operation not valid for the session status	The operation requires a different lifecycle status, for example only `scheduled` sessions can be updated and actions require an `active` session.	Read the session status first and retry when the session reaches the required state.
`unsupported_capability`	`422`	Capability not supported on this platform	The requested capability, such as avatar video, is not available on the detected meeting platform.	Check the platform’s capabilities before enabling the feature, or omit it.
`not_configured`	`503`	Feature not configured	A required integration is not configured for the account.	Complete the feature’s setup for your account before retrying.
`tts_error`	Text-to-speech failure	The speak operation failed in the upstream text-to-speech service.	Retry the speak action; if the failure persists, try a different `voice`.
`provider_error`	Provider failure	The upstream meeting provider failed, for example a recording-media deletion whose outcome is unknown.	Retry the operation and confirm the result with a follow-up read.
`auth_unavailable`	Authentication service unavailable	The authentication backend could not be reached.	Retry with backoff.
`internal_error`	Internal server error	An unexpected failure inside the Meeting service.	Retry with backoff; contact support if the failure persists.

Join a Meeting — create a meeting session and send the bot
Controlling the Bot — actions that require an active session

Meeting (Beta)

Join a Meeting

During the Meeting

After the Meeting

Integration

API Reference

WebSocket

For AI Agents

Meeting API Errors

Meeting Error Codes

​Meeting Error Codes

​Related

Meeting Error Codes

Related