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`	Only non-dispatched bots can be updated	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.
`update_bot_failed`	Cannot validate partial without join call task	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.
`cannot_delete_bot`	The specified Bot cannot be deleted. Only scheduled bots which have not yet joined a call can be deleted.	This occurs when you attempt to delete a bot that is already alive (has already started joining or joined a call). You can call the Remove Bot From Call endpoint if you'd like to remove the bot from the 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 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.

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.