API Errors

API Error Codes

Recall's API uses the following HTTP codes:

Adhoc Bot Pool Errors

An HTTP 507 error occurs when you are trying to create an "adhoc bot", and no bots are available in the "adhoc bot pool". Adhoc bots are bots that are created without specifying a join time in advance. They join the call immediately, and are claimed from a pool of idle bots that we scale predictively based off of expected load.

Sometimes many bots are requested at once, which depletes the idle bot pool. Any attempts to create an adhoc bot at this point will result in a HTTP 507 error, until new bots are automatically launched to replenish the pool.

This replenishment results in new bots being available within a few seconds to a minute or two, so if you receive the HTTP 507 error you should retry the request every 30 seconds.

You can avoid the HTTP 507 error entirely by using scheduled bots. These are bots that have a join time specified in advance, either through the create_bot.join_at parameter or by using the Recall.ai calendar integration. When you create a scheduled bot, we launch and reserve a bot specifically for you, which guarantees that it will join the call at the indicated time.

400 Error Message Reference

Fatal Errors

When you get a Bot Status Change Webhook Event from a bot with status fatal, you can check the data.status.sub_code field to get a description of the error. The complete list for possible sub_code can be found here Bot Error Codes

403 Request Blocked

Our WAF may block your request and return a 403 status code if your payload is flagged as potentially malicious or malformed.

In this case, response body will have a request_blocked code:

{
    "code": "request_blocked",
    "detail": "Request was blocked due to security rules. This is likely due to providing a localhost URL in your payload. More details: https://docs.recall.ai/reference/errors#/403-request-blocked"
}

Common scenarios include:

• Providing a localhost URL in your payload
• Providing a body (including a null body) in a GET request

📘

Tip: If you're trying to test locally, instead of providing a localhost URL, you should use an ngrok tunnel to expose your local server through a public endpoint.

See Testing Webhooks Locally for a full setup guide.

507 Insufficient Storage

The 507 error only occurs for ad-hoc bots and indicates there are no more ad-hoc bots available in our "pool" of ad-hoc bots. Read more about scheduled bots, ad-hoc bots, and the ad-hoc bot pool below.

Scheduled bots

📘

Scheduled bots always join on-time and will never encounter 507 errors

A scheduled bot is a bot created via the Create Bot or Schedule Bot For Calendar Event endpoints with a join_at set more than 10 minutes from the time you make the request.

You should try using scheduled bots wherever possible because:

• Scheduled bots guarantee your bots join the meeting on time every time
• Scheduled bots will never run into a 507 error (no more ad-hoc bots in the ad-hoc bot pool claim)
• Scheduled bots come at no extra charge and reserves a dedicated instance, separate from the ad-hoc bot pool (described below)

Updating scheduled bots

• The bot's original join_at is more than 10 minutes from the current time - You can update all properties on the bot using the Update Scheduled Bot endpoint.
  • If setting a new join_at, the new join_at needs to be more than 10 minutes from the current time. If the new join_at is less than 10 minutes from the current time, you will then need to delete the scheduled bot and create a new bot instead.
• The bot's original join_at is less than 10 minutes from the current time - You can update all properties using the Update Scheduled Bot endpoint.
• Once the bot starts joining the call - You cannot update the bot

Deleting scheduled bots

• More than 10 minutes before the bot's join_at - You must call the Delete Scheduled Bot endpoint.
• Less than 10 minutes before the bot's join_at - You must call the Remove Bot From Call endpoint.
• Once the bot starts joining the call - You must call the Remove Bot From Call endpoint.

Ad-hoc bots

📘

When to use ad-hoc bots

Ad-hoc bots are meant to fill in the gaps where you can't schedule bots more than 10 minutes in advance (e.g. ad-hoc/last minute meetings).

You should use ad-hoc bots sparingly, opting for scheduled bots whenever possible

An ad-hoc bot is a bot created via the Create Bot or Schedule Bot For Calendar Event endpoints with a join_at set less than 10 minutes from the time you make the request.

Updating ad-hoc bots

• Less than 10 minutes before the bot's join_at - You can update all properties except the join_at field using the Update Scheduled Bot endpoint
• Once the bot starts joining the call - You cannot update the bot

Deleting ad-hoc bots

• Less than 10 minutes before the bot's join_at - You must call the Remove Bot From Call endpoint.
• Once the bot starts joining the call - You must call the Remove Bot From Call endpoint.

Finding your concurrent ad-hoc bot limit

You can find a given workspace's concurrent ad-hoc bot limit in the dashboard under Developers > Rate Limits

Ad-hoc bot pool

Starting up a bot takes some time (10 minutes) before it is ready to join a meeting since each bot runs on its own dedicated machine. Because of this, we maintain a pool of "warm" bot instances that are already running in cases where you need to claim a bot last minute (or ad-hoc)

Each region has its own dedicated ad-hoc bot pool and this ad-hoc bot pool is shared among all developers in a region. The ad-hoc bot pool is calibrated and adaptive, constantly being replenished and grows with active usage. It is designed to maintain sufficient warm bot instances to support peak usage at any given time.

That said, the bot pool can still be drained during short periods with very high ad-hoc bot activity in a specific region. In these cases, there are no warm bot instances available and you will need to wait until more bot instances have warmed up before you can claim an ad-hoc bot

❗️

507 error: the limitation of ad-hoc bots

If you rely on ad-hoc bots, you will eventually encounter 507 errors indicating there are no more ad-hoc bots left to claim.

When you encounter a 507 error, you can:

• Retry the request every 30s until you're able to claim an ad-hoc (usually within a few retries).
• Audit your workflows to see if you can use scheduled bots which never encounter 507 errors

What to do when you encounter a 507

📘

Use scheduled bots wherever possible

Scheduled bots will never encounter a 507 error

When you encounter a 507 error, you can retry the request every 30s. You should be able to claim an ad-hoc bot within a few retries.