Troubleshooting - MeetingKit

Request errors

Every error comes back as { "errors": [{ "code", "message", "field" }] }: branch on code, read message, and field names the input on validation errors. See Errors.

Status	When	What to do
`400`	A field is malformed or unknown, or a required one is missing.	Fix the request. Sending it unchanged fails again.
`401`	The API key is missing or wrong, or it is not an owner or admin of the workspace.	Check the key and the workspace.
`403`	The workspace’s plan lacks notetaker customization (`plan_upgrade_required`).	Company defaults and branding need that plan.
`404`	Nothing with that id in a workspace the key can see.	Check the id and its prefix (`mtg_`, `mem_`, `bot_`…).
`409`	The resource’s state forbids it: `bot_not_editable`, `bot_not_cancellable`, `bot_already_recording`, `meeting_not_upcoming`, `calendar_already_connected`…	Read the resource: it has moved on.
`422`	A value is invalid: a bad `meeting_url` or `return_url`, a template the workspace can’t use…	Read `errors`, fix the value.
`429`	A rate limit.	Wait `Retry-After` seconds, then send the same request again.
`5xx`, timeout	Something failed on our side, or the connection dropped.	Retry with backoff. Creating a bot is safe to retry.

Why a bot failed

A bot that ends without a result has status: "failed", a reason to branch on, and a failure_message for your logs. It arrives on bot.failed and on GET /bots/{id}.

`reason`	What happened	What to do
`no_recording`	The meeting ended with nothing recorded: nobody admitted the bot, or nobody spoke.	Tell the user it wasn’t recorded. Don’t retry automatically.
`invalid_meeting_url`	The provider couldn’t open the link.	Check the link, then send a new bot.
`bot_error`	Another fatal error in the call.	Send a new bot if the meeting is still on.
`transcription_failed`	The call was recorded but processing failed.	Contact support with the bot id. The recording is kept.

The bot also leaves on its own: after 15 minutes in a waiting room, 10 seconds after everyone else left, or after 20 minutes of silence. A bot that recorded something before leaving goes on to completed; one that recorded nothing fails with no_recording.

What to check

You see	Check
No meetings after connecting a calendar	The connection is `active` and `last_synced_at` is recent (`GET /calendar_connections?member_id=`).
A meeting the user expected isn’t there	It is on the calendar they connected, under the account in `account_email`.
The same call listed twice	The workspace uses one calendar source: connected calendars or pushed events, not both.
”Won’t record” on a meeting they want	`settings.sources["recording.enabled"]`: the assignment that decided, or a `reason` (`no_meeting_url`, `unsupported_platform`, `member_paused`…).
A bot `queued` long after `join_at`	`join_at` is the time you meant, with the right offset.
A bot `joining` for minutes	Someone in the call admits it: many calls hold guests in a waiting room.
Speakers unnamed	The meeting’s participants carry emails; names improve as people recur.
Two bots in one call	Both requests used the same `workspace_id`, link and `join_at`. See One bot per meeting.
`processing` for hours	Contact support with the meeting id.
No webhooks arrive	The endpoint is in the meeting’s workspace and names the event in `enabled_events`. Then find the event in `GET /webhook_events`: the answer your server gave, and redeliver it.
Webhooks fail verification	You sign the raw body, not re-serialized JSON, with the full secret including `whsec_`.

Contact support

Write to support@happyscribe.com with the workspace id, the meeting, bot or connection id, what you expected and what you got, and when. Never send your API key or webhook secret.