> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.vapi.ai/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.vapi.ai/_mcp/server.

# Handle API Request Tool latency and retries

> Learn how API Request Tool timeouts and failed HTTP requests behave, keep callers informed, and handle safe retries in a service you control.

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](/security-and-privacy/api-keys) 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.

> **Note**
>
> 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](/tools/api-request/quickstart) and adds messages for the caller.

#### Dashboard

#### Open the tool

Open the [Dashboard](https://dashboard.vapi.ai), 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](/_fern-files/_img/01021d77998a180d0751c089229eed31c48caee3d98169edca116aeb3aaba1a2.webp)![Vapi Dashboard Request Response Delayed message configured to play after 5000 milliseconds](/_fern-files/_img/b8ce24245dba3a48b0ed5ffc582d6c79bc6b7b3674d05ef97aeb5b090440d681.webp)![Vapi Dashboard Request Failed system message with recovery instructions](/_fern-files/_img/d8030a6e929be92cb1216103ca05d97c4bfc59828639b61bb13359792ac8374e.webp)

#### Publish the tool

Select **Publish**.

#### cURL

Set your API key and the ID of the tool created in the quickstart:

```bash
export VAPI_API_KEY="YOUR_VAPI_API_KEY"
export VAPI_TOOL_ID="YOUR_TOOL_ID"
```

Update the tool with the [Update Tool endpoint](/api-reference/tools/update):

```bash
curl --request PATCH \
  --url "https://api.vapi.ai/tool/$VAPI_TOOL_ID" \
  --header "Authorization: Bearer $VAPI_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "timeoutSeconds": 20,
    "messages": [
      {
        "type": "request-start",
        "content": "Let me submit that order.",
        "blocking": false
      },
      {
        "type": "request-response-delayed",
        "timingMilliseconds": 5000,
        "content": "The order system is taking a little longer than expected."
      },
      {
        "type": "request-failed",
        "role": "system",
        "content": "The order request failed. Apologize, explain that the order was not confirmed, and offer to try again only after the caller agrees."
      }
    ]
  }'
```

The example does not set `backoffPlan`. A timeout does not prove that the order-creation request had no effect, so check for an existing order before submitting another one.

## 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. |

> **Warning**
>
> 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](/api-reference/tools/create) and [Update Tool](/api-reference/tools/update) API references. To diagnose failed tool calls, see [Troubleshoot tools](/tools/custom-tools-troubleshooting).