Handle API Request Tool latency and retries

API Request Tools do not currently retry a request after a non-2xx response or a timeout, even when backoffPlan is set. Set a timeout and tool messages so the assistant can handle a slow or failed request.

Prerequisites

An existing API Request Tool
For cURL requests, a Vapi API key and the tool ID

Choose a timeout

timeoutSeconds controls how long the tool waits for an API request. It defaults to 20 seconds and accepts values from 1 to 300 seconds.

When the timeout expires, the assistant receives Request timed out. Vapi stops waiting for the response, but the destination API may continue processing the request. Choose a timeout that accommodates the API’s normal response time without leaving the caller waiting unnecessarily.

The Dashboard currently exposes tool messages but not timeoutSeconds. Use the API to set the timeout. If you omit timeoutSeconds, it defaults to 20 seconds.

To observe timeouts and failed responses before production, use a non-production endpoint you control that can delay responses or return failure statuses. Check that endpoint’s logs to see whether it received or completed a request.

Protect the coffee-order request

Creating an order changes server state. A timed-out request may still create the order, so check its outcome before submitting it again. If your order API supports an idempotency key or another form of duplicate protection, use it so a repeated request cannot create a second order.

The following configuration applies a 20-second timeout to the coffee-order quickstart and adds messages for the caller.

Dashboard

cURL

Open the tool

Open the Dashboard, select Tools, then select createCoffeeOrder.

Configure tool messages

Expand Messages. Set Request Start to Custom, then add the remaining message stages with Add Message:

Stage	Configuration
Request Start	`Let me submit that order.`
Request Response Delayed	After `5000` milliseconds: `The order system is taking a little longer than expected.`
Request Failed	Enable AI-generated message (content is used as a prompt for the model), then enter: `The order request failed. Apologize, explain that the order was not confirmed, and offer to try again only after the caller agrees.`

Do not add Request Complete. The model can then use the API response to read the server-calculated total and order number to the caller.

Vapi Dashboard Request Start message set to Let me submit that order — Acknowledge the order when the request starts

Vapi Dashboard Request Response Delayed message configured to play after 5000 milliseconds — Keep the caller informed when the response is delayed

Vapi Dashboard Request Failed system message with recovery instructions — Guide the model when the request fails

Publish the tool

Select Publish.

Understand retries and timeouts

An API Request Tool accepts a backoffPlan in its configuration, but the current execution path does not use it for automatic retries. A non-2xx response or a timeoutSeconds timeout ends that tool invocation without a retry. Values such as maxRetries and excludedStatusCodes do not change this behavior for API Request Tools.

Result	What happens
Non-2xx HTTP response	The assistant receives a failed tool result. The tool does not send another request automatically.
Timeout before a response	The assistant receives `Request timed out`. The destination API may still finish processing the original request.

The assistant may invoke the tool again as a separate action. Treat that as a new request, and check whether repeating it is safe. Server URL webhook delivery uses a separate retry path; its backoffPlan behavior does not establish API Request Tool retry behavior.

To confirm how many requests reached your API, check the destination endpoint’s logs.

Retry through a service you control

For an upstream request that is safe to repeat, point the API Request Tool at a service or proxy you control. That service can make a bounded number of upstream attempts, wait between them, and return a result before the tool’s timeoutSeconds expires.

Situation	Handling
Temporary failure on a read-only request	Retry the upstream request in your service with a small limit and delay.
`400`, `401`, `403`, or `404` response	Fix the request, credentials, permissions, or resource before trying again.
Order, payment, message, booking, or other state-changing request	Check the outcome and use idempotency or duplicate protection before repeating it.

Do not ask the assistant to repeat a state-changing request after a timeout until your service can determine whether the first request completed.

Keep the caller informed

Tool messages control what the caller hears while a request is running and after it finishes.

Message type	When it runs	Recommended use
`request-start`	When the tool starts	Acknowledge the action. If omitted, Vapi uses a default filler message.
`request-response-delayed`	When the configured delay is reached	Explain that the request is still running. Use different timings for staged updates.
`request-complete`	When the request succeeds	Use a fixed assistant message only when it does not need response data. Use the system role to guide a model-generated response.
`request-failed`	When the request fails	State what the caller should do next, or use the system role to guide an error-aware response.

For request-complete and request-failed, the default assistant role speaks the configured content instead of asking the model to respond. Use the system role when the response should account for tool results or conversation context.

For the complete field definitions, see the Create Tool and Update Tool API references. To diagnose failed tool calls, see Troubleshoot tools.