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.
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.
	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 (>6 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.
`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