> ## 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. |
| `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`, not still `syncing` (`GET /calendar_connections?member_id=`), and the meetings start within the next 28 days. `active` with `last_synced_at` still `null` more than 30 minutes after `connected_at`, for a member whose meetings are recorded, means the first sync never finished: disconnect it (`DELETE /calendar_connections/{id}`) and send the member a new connect link. |
| 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@meetingkit.com](mailto:support@meetingkit.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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.