Skip to content

Errors

Errors share one shape:

{ "error": { "code": "too_early", "message": "the call is not open for joining yet", "opens_at": "2026-10-20T03:50:00Z" } }

Branch on code. message is for logs and may change. opens_at is only present for too_early.

Codes

HTTP code Meaning What to do
400 invalid_request A field failed validation; message says which Fix the request
400 invalid_body Malformed JSON, an unknown field, or a body over 64 KB Fix the request
401 unauthenticated Missing, malformed, expired or wrongly signed token, or an unknown or revoked key Get a fresh token; check the key and secret
403 forbidden Authenticated, but not allowed (for example, not the host)
403 not_invited The call is listed_only and this user isn't a member Add them as a member, or use any_client_user
404 not_found No such call or invite, or it isn't visible to you
404 invite_not_found Unknown invite code
409 too_early The join window hasn't opened yet; see opens_at Show a countdown
409 too_late The join window has closed
409 call_ended The call has ended
409 call_cancelled The call was cancelled
409 call_full max_participants reached Retry later or raise the limit
409 call_not_live, already_recording, not_recording Recording state conflicts Check the call and recording state
409 archived, not_ready, not_archived Recording isn't downloadable or restorable yet See Recording
410 expired Recording passed its retention period
501 recording_disabled Recording isn't enabled on this server
409 call_closed You tried to edit an ended or cancelled call
409 org_default, not_active Rate management conflicts
410 invite_expired Past expires_at Create a new invite
410 invite_revoked The invite was revoked
410 invite_exhausted max_uses reached
429 rate_limited More than 20 join attempts in a minute Back off
500 internal Something went wrong on Tele's side Retry with backoff; report it if it persists
503 not_ready /readyz only: the database is unavailable

Retries

  • 5xx and 429 are safe to retry with exponential backoff.
  • Joins: each successful join consumes one use of a max_uses invite. Retry a join only if the previous attempt failed.
  • POST /v1/calls isn't idempotent, so a retry after a timeout can create a duplicate call. Use GET /v1/calls to check before retrying.