> ## Documentation Index
> Fetch the complete documentation index at: https://docs.meetingkit.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Request errors, why a bot failed, and what to check when meetings, recordings or webhooks are not what you expect.

## 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](/api-reference/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](/meetingkit/send-bot#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`](/api-reference/webhook-events/list-webhook-events): the answer your server gave, and [redeliver](/api-reference/webhook-events/redeliver-a-webhook-event) 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](mailto: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.