Skip to navigation

Errors

How the MeetStream API reports errors, every status code, what causes it, and how to fix it.
View as Markdown

MeetStream reports problems in two places: an HTTP error when a request is rejected, and a bot status or webhook when a bot that was created successfully cannot do its job. This page covers HTTP errors. For bot-level statuses, ErrorReason codes and messages on Zoom, Google Meet and Microsoft Teams, see the Bot status and error code reference.

Most errors return a JSON body with a message field:

{ "message": "meeting_link is required." }

A few endpoints return error instead, with extra fields: in-meeting commands (send message, send image, pause, resume), the credit check on create_bot, the deduplication conflict on create_bot, and signed-in login management. Read both keys:

body = resp.json()
reason = body.get("message") or body.get("error")

Branch on the HTTP status code first, then log the text for the specifics.

Status codes at a glance

StatusMeaningTypical cause
200 OKSuccessRequest completed
201 CreatedBot createdPOST /bots/create_bot succeeded
202 AcceptedStill processing, or command acceptedData not ready yet (transcript, audio, video, chat, per-participant streams); poll again
400 Bad RequestValidation errorMissing or invalid field, unsupported meeting link, unsupported provider, value out of range
401 UnauthorizedAuthentication requiredThe key is valid but is not a workspace API key. Send a workspace key as Authorization: Token YOUR_API_KEY
403 ForbiddenNot allowedMissing or invalid API key, another account’s bot, or not enough credits
404 Not FoundResource or route not foundUnknown bot_id or transcript_id, or wrong path
409 ConflictConflicts with current stateDeduplication conflict, bot not in the meeting yet, or a signed-in login is busy
429 Too Many RequestsRate or capacity limitPrepaid bot creation limit, in-meeting command rate limit, or no signed-in login available
500 Internal Server ErrorServer errorTransient MeetStream error; retry with backoff
503 Service UnavailableTemporarily unavailableA dependency is not ready; retry with backoff
507Idempotent replayA retried Idempotency-Key replayed the original bot; treat as success

For REST API requests, the Authorization header is Token YOUR_API_KEY (not Bearer). The MCP server uses Bearer. See MeetStream MCP server. A missing key, an invalid or revoked key, or a key sent with Bearer returns 403 Forbidden with { "message": "Forbidden" }. See Authentication.

Authentication and access errors (403)

BodyCauseFix
{ "message": "Forbidden" }The Authorization header is missing, uses Bearer, or the key is wrong or revoked.Send Authorization: Token YOUR_API_KEY. Create a key in the dashboard.
A body that says you do not have access to this botThe bot_id belongs to another workspace. Bot and media endpoints return 403, and Remove Bot and Get Stop Status return 404.Use a key from the workspace that created the bot.
{ "error": "Low credits please recharge", "available_credits": ..., "minimum_required": ... }create_bot on a pay-as-you-go account with less than 30 minutes of credit.Add credits in Billing.
{ "error": "Low credits please recharge", "active_bots": 1 }Balance under $1 while another bot is running.Add credits, or wait for the running bot to finish.

Treat a 401 Unauthorized like a 403: check that you send a workspace API key as Token YOUR_API_KEY. Very high request rates from one IP address can also be blocked with 403.

Validation errors (400)

Returned when the request fails validation, before any bot is created, so a 400 never spawns a bot or consumes credits. The message names the exact problem. Common cases:

messageCause
meeting_link is required.POST /bots/create_bot sent without meeting_link
meeting_link host '...' is not a supported meeting platform. Expected Google Meet (meet.google.com), ...The link is not a Zoom, Google Meet, Microsoft Teams or WhatsApp call link
meeting_link looks like the GMeet site root or a marketing page, not a meeting URL: '...'The link is a site root or a page such as /signin instead of a meeting
Zoom bots require a connected Zoom app or Zoom credentials in the user profileNo Zoom Meeting SDK credentials configured; see Zoom setup
waiting_room_timeout for GMeet must not exceed 600 seconds (got 900)An automatic_leave value is outside the per-platform range
in_call_recording_timeout must be at least 600 seconds (got 300)automatic_leave.in_call_recording_timeout below 600
recording_permission_denied_timeout must not exceed 300 seconds (got 400)Value above 300 (accepted range is 60 to 300)
live_transcription_required.webhook_url is provided but no streaming provider found...Set a live provider in recording_config.transcript.provider, such as deepgram_streaming or assemblyai_streaming, or meeting_captions. See live transcription
join_at must be in the futureScheduled time is in the past
Invalid join_at format: Cannot schedule bot more than 90 days (3 months) in the future. ...join_at is more than 90 days ahead
Unsupported transcription provider: <name>The provider key is not one MeetStream accepts
Messages that end in not configured in user profileYour account has no API key saved for that provider. Add the key in Integrations, or use the meetstream provider

Platform-specific 400s (Zoom token URLs, Google and Teams signed-in domains, teams.live.com sign-in) are listed in HTTP errors from create_bot.

400 messages are specific and actionable. Always log them. Fix the request and retry; a 400 is never transient.

Not found (404)

The resource or route doesn’t exist. Body varies by what was missing:

BodyCause
{ "message": "Bot not found" }Unknown bot_id (also returned for a scheduled bot that was deleted)
{ "message": "Transcript not found" }Unknown transcript_id
{ "message": "Not Found" }Unknown path, or a valid path called with an unsupported method

Conflict (409)

BodyCauseFix
{ "error": "deduplication_key already bound to a different meeting", "existing_bot_id": "...", "existing_meeting_url": "..." }A deduplication_key was reused for a different meeting link. Replaying it with the same link returns 200 and the existing bot.Use a new key for a new meeting. See Deduplication & Idempotency Keys.
A bot is already scheduled for this eventA calendar event already has a scheduled bot.Change it with PATCH /calendar/scheduled_bots/{bot_id} instead.
{ "error": "Bot is not currently in a meeting.", "bot_status": ..., "detail": ... }An in-meeting command was sent while the bot was still in the lobby or had already left.Wait for bot.inmeeting before sending commands.
teams.sign_in_email '...' is currently in useA pinned Teams login is serving another bot.Retry later, or set strict_email: false.
{ "code": "TRANSCRIPTION_NOT_ENABLED", "message": "Transcription was not enabled for this bot." }The bot was created without a post-call provider.Start a run with POST /api/v1/bots/{bot_id}/transcribe.
No transcript was generated because the bot was not admitted to the meeting.The bot ended as NotAllowed, Denied or Failed, so there is no audio.Check the bot’s terminal status.

Rate and capacity limits (429)

Prepaid accounts can create 5 immediate or near-term bots per minute and 50 per hour, in rolling windows. Bots scheduled at least 10 minutes ahead and idempotent or deduplication replays do not count. The create response includes Retry-After (seconds), retry_after, limit, and window (minute or hour). See Create Bot Payload Reference.

BodyCauseFix
{ "error": "rate_limit_exceeded", "limit": 5 or 50, "window": ..., "retry_after": ... }Prepaid create_bot limit for immediate or near-term bots.Wait for Retry-After, or schedule the bot at least 10 minutes ahead.
{ "error": "Rate limit exceeded", "limit": 30, ... }More than 30 in-meeting commands per minute for one bot (5 per minute for screenshots). The response includes a Retry-After header.Wait for Retry-After seconds, then retry.
All Teams logins under domain '...' are currently in useEvery Teams signed-in login is serving a bot.Add logins or retry later. See Teams signed-in bots.
All N active logins under domain '...' are at capacity (30 active sessions each)Every Google signed-in login is at capacity.Add logins or retry later. See Google signed-in bots.

Idempotent replay (507)

If you retry POST /bots/create_bot with the same Idempotency-Key, MeetStream returns 507 with the original bot’s details: no new bot, no extra charge. Treat 507 as success:

if resp.status_code in (201, 507):
    bot = resp.json()   # same bot on 507 as on the original 201

By contrast, a deduplication_key replay returns 200 (looks like a normal create). Both are documented in the Deduplication & Idempotency guide.

Still processing (202)

202 means the request was accepted but the data isn’t ready. Poll again; don’t treat it as an error.

  • Transcript not ready: GET /transcript/{transcript_id}/get_transcript returns { "message": "Transcript is still being processed. Current status: <state>" }.
  • Per-participant streams: get_audio_streams / get_recording_streams return { "audio_status": "in_progress", "message": ... } while the bot is still in the meeting.
  • Mixed audio, video and chat: get_audio, get_video and get_chats return 202 until post-call processing for that artifact finishes.

Live providers do not create a post-call transcript. With a live-only provider (*_streaming), the text goes to your live webhook during the call, and transcript_id is null. Store the live stream as the transcript of record, or start a post-call run with POST /api/v1/bots/{bot_id}/transcribe. Put a limit on any polling loop.

Server errors (500 / 503)

Most 500 and 503 responses are temporary. Retry with exponential backoff.

One 500 is final: when get_transcript returns a message that starts with Transcript processing failed, the transcription run ended. Read the message, correct the provider settings if needed, and start a new run with POST /api/v1/bots/{bot_id}/transcribe.

If any other 500 repeats, contact support@meetstream.ai with the request time and any bot_id.

Operational errors (surfaced via bot status and webhooks, not HTTP)

Some failures happen after a successful 201: the bot was created, then couldn’t join or had to leave. These arrive as a terminal webhook on your callback_url or workspace endpoints, and in the bot’s status. Every ending uses event: "bot.stopped"; the reason is in bot_event.

bot_event · bot_statusMeaningWhat to do
bot.notallowed · NotAllowedNobody admitted the bot before waiting_room_timeoutAdmit bots faster, raise waiting_room_timeout, or use a signed-in bot for Google Meet or Microsoft Teams
bot.denied · DeniedThe host denied the bot entryNothing automatic; the host must admit it
bot.failed · FailedThe meeting blocked the join (invalid link, restricted, not started, ended, sign-in required)Read ErrorReason in /detail and follow the reference
bot.failed · ErrorA credential, token, link-format or sign-in issue, or a join that could not completeRead the message and follow the reference
bot.errorA live transcription provider failed while the bot kept running, or a scheduled bot was rejected when it tried to startCheck your provider keys, or read the message and schedule a new bot
transcription.failed · status_code: 500Post-call transcript run failedRead message (for example "Deepgram API error: 401" means a provider key issue); re-run with POST /bots/{bot_id}/transcribe
Bot status and error code reference

Every status, bot_event, ErrorReason and exact message on Zoom, Google Meet and Microsoft Teams, with causes and fixes.

Handling errors well

Retry only what's retryable

Retry 429, 500 and 503 with backoff, honoring Retry-After when present. A get_transcript 500 that starts with Transcript processing failed is final. Never retry a 400; fix the request first.

Make retries safe

Send an Idempotency-Key on create_bot so a network retry replays the original bot (507) instead of creating duplicates.

Cap your polling

Put a limit on transcript polling; live-only providers create no post-call transcript.

Always log the text

Every error carries a specific message or error; surface it so 400 and 404 causes are obvious.