API Errors

API Error Codes

Recall's API uses the following HTTP codes:

Error Code	Meaning
200	OK -- Everything worked as expected.
201	Bot created successfully.
400	There was something wrong with your request. Check the response body for a detailed error message. For the error message reference, go here.
401	Unauthorized -- No valid API key provided.
402	(Self-serve customers) Insufficient credit balance -- Top up balance in the dashboard.
403	Request Blocked -- Our WAF blocked your request due to an issue with your payload.
405	Method is not allowed for the endpoint -- if calling DELETE, the bot has already been dispatched.
409	Conflict -- please retry with exponential backoff (see Scheduling Guide and Idempotency)
429	Too many requests: Retry after the duration specified in the returned `Retry-After` header (`Retry-After: <delay-seconds>`).
502	Our servers have dropped the request due to high load -- please retry.
503	Our servers have dropped the request due to high load -- please retry.
504	Our servers have dropped the request due to high load -- please retry.
507	Out of adhoc bots -- Please retry in 30 seconds.

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

Code	Response Body	Description
`teams_blacklisted_tenant`		Microsoft Teams has certain tenants that do not allow bots to join their calls. This error occurs when you attempt to create a bot for a meeting hosted by one of these tenants. There is no workaround for this error.
`update_bot_failed`	Only non-dispatched bots can be updated	This typically happens when Update Scheduled Bot is called on a bot that was already sent to a call. You can verify a scheduled bot was already sent to a call when you receive the `joining_call` webhook event.
`update_bot_failed`	Not enough time to launch new bot	This typically happens when Update Scheduled Bot is called with an updated `join_at` too close to the present (`<10` minutes). There is a minimum amount of time it takes for us to launch a scheduled bot, and we cannot update a scheduled bot's `join_at` too close to the present for that reason. To handle this, you should delete the scheduled bot and create a new adhoc bot to join the meeting instead.
`cannot_command_completed_bot`	Cannot send a command to a bot which has completed(is shutting/has shut down/has errored).	This error occurs when a bot is shutting down, has shut down, or has errored, and you call an endpoint that requires the bot to be in the call - for instance, Remove Bot From Call.
`cannot_command_unstarted_bot`	Cannot send a command to a bot which has not been started.	This occurs when you call an endpoint that requires the bot to be in a call while the bot has already been terminated - for instance, Remove Bot From Call.

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 if the payload is flagged as potentially malicious or malformed.

In this case, the HTML body in the response will look something like this:

<body>
    <h1>403 ERROR</h1>
    <h2>The request could not be satisfied.</h2>
    <hr noshade size="1px">
    Request blocked.
    We can't connect to the server for this app or website at this time. There might be too much traffic or a
    configuration error. Try again later, or contact the app or website owner.
		...
</body>

Common scenarios include:

Providing a localhost URL in the payload
Providing a body (including a null body) in a GET request
Providing a raw IP address in the request payload

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

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
Scheduled bots come at no extra charge

Updating scheduled bots

More than 10 minutes before the bot's join_at - You can update all properties on the bot
Less than 10 minutes before the bot's join_at - You can update all properties except the join_at field
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

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.

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) and should be used sparingly.

Updating ad-hoc bots

Less than 10 minutes before the bot's join_at - You can update all properties except the join_at field
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.

Ad-hoc bot pool

Because each bot runs on its own dedicated machine, starting up a bot takes some time (10 minutes) before it is ready to join a meeting. 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 adaptive, constantly being replenished and grows with active usage.

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.

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.