Updated API tool retry behavior

fern/apis/api/openapi-overrides.yml

@@ -2214,10 +2214,13 @@ components:
     CreateApiRequestToolDTO:
       title: CreateApiRequestToolDTO
       description: >-
-        Configuration used to create a reusable tool that sends HTTP requests
-        to a configured API and can authenticate, retry failures, and extract
-        variables from responses.
+        Configuration for a reusable tool that sends HTTP requests to an API
+        and supports authentication and response variable extraction.
       properties:
+        backoffPlan:
+          description: >-
+            A backoff plan can be saved on an API Request Tool, but API Request
+            Tools do not currently retry after a non-2xx response or a timeout.
         method:
           description: The HTTP method used for the API request.
     CreateCodeToolDTO:
@@ -4243,9 +4246,13 @@ components:
       title: CreateOutputToolDTO
     ApiRequestTool:
       description: >-
-        A reusable tool that sends HTTP requests to a configured API and can
-        authenticate, retry failures, and extract variables from responses.
+        A reusable tool that sends HTTP requests to an API and supports
+        authentication and response variable extraction.
       properties:
+        backoffPlan:
+          description: >-
+            A backoff plan can be saved on an API Request Tool, but API Request
+            Tools do not currently retry after a non-2xx response or a timeout.
         method:
           description: The HTTP method used for the API request.
     CodeTool:
@@ -4366,9 +4373,13 @@ components:
         account.
     UpdateApiRequestToolDTO:
       description: >-
-        Fields used to update an API-request tool, including its URL, HTTP
-        method, authentication, request data, retries, and response handling.
+        Fields used to update an API Request Tool, including its URL, HTTP
+        method, authentication, request data, and response handling.
       properties:
+        backoffPlan:
+          description: >-
+            A backoff plan can be saved on an API Request Tool, but API Request
+            Tools do not currently retry after a non-2xx response or a timeout.
         method:
           description: The HTTP method used for the API request.
     UpdateDtmfToolDTO:

fern/tools/api-request.mdx

@@ -37,7 +37,6 @@ Keep calculations and business rules on your server when they must be determinis
 | Server-resolved values | Supports fixed values and Liquid templates in the URL, request headers, and static body fields. |
 | Authentication | Applies a reusable Vapi credential through `credentialId`. |
 | Timeout | Uses 20 seconds by default; `timeoutSeconds` accepts 1–300 seconds. |
-| Retries | Does not retry unless `backoffPlan` is configured. Fixed and exponential backoff are supported. |
 | Execution | Waits synchronously for the destination API before returning a result to the assistant. |
 | Response data | Makes the current result available to the model. Variable extraction requires a JSON response. |
 
@@ -53,7 +52,7 @@ See the [Create Tool](/api-reference/tools/create) and [Update Tool](/api-refere
     Configure the endpoint, request body, headers, static body fields, and Liquid values.
   </Card>
   <Card title="Handle latency and retries" icon="clock" href="/tools/api-request/reliability">
-    Set timeouts, retry safe requests, and keep callers informed while a request runs.
+    Set timeouts, handle failures safely, and keep callers informed while a request runs.
   </Card>
   <Card title="Handle responses and errors" icon="circle-exclamation" href="/tools/api-request/response-handling">
     Design response contracts, test failures, and inspect tool results.

fern/tools/api-request/quickstart.mdx

@@ -273,7 +273,7 @@ The assistant should call the API only after confirmation. It should then read a
     Add headers, static fields, Liquid values, and authentication.
   </Card>
   <Card title="Handle latency and retries" icon="clock" href="/tools/api-request/reliability">
-    Configure timeouts, caller messages, and safe retry behavior.
+    Configure timeouts, caller messages, and safe handling for failed requests.
   </Card>
   <Card title="Handle responses and errors" icon="circle-exclamation" href="/tools/api-request/response-handling">
     Design response contracts and help the assistant recover from failures.

fern/tools/api-request/reliability.mdx

@@ -1,11 +1,11 @@
 ---
-title: Handle API Request tool latency and retries
-subtitle: Set request timeouts, keep callers informed, and retry only requests that are safe to repeat
-description: Configure API Request Tool timeouts, retry backoff, excluded status codes, and caller messages for slow or failed HTTP requests with practical cURL examples.
+title: Handle API Request Tool latency and retries
+subtitle: Set request timeouts, explain failures, and handle safe retries in your own service
+description: Learn how API Request Tool timeouts and failed HTTP requests behave, keep callers informed, and handle safe retries in a service you control.
 slug: tools/api-request/reliability
 ---
 
-API Request Tools wait for the destination API to respond before the assistant continues. Configure a timeout for every tool, use messages to keep the caller informed, and enable retries only when repeating the request cannot create an unwanted side effect.
+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
 
@@ -16,19 +16,19 @@ API Request Tools wait for the destination API to respond before the assistant c
 
 `timeoutSeconds` controls how long the tool waits for an API request. It defaults to 20 seconds and accepts values from 1 to 300 seconds.
 
-Choose a timeout that accommodates the API's normal response time without leaving the caller waiting unnecessarily. A longer timeout does not fix an unreliable endpoint, and retries can increase the time before the tool returns a final result.
+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` or `backoffPlan`. Use the API to change timeout or retry behavior. If these fields are omitted, the timeout defaults to 20 seconds and the request is not retried.
+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.
 </Note>
 
-To observe timeout, delayed-message, and retry behavior before production, use a non-production endpoint you control that can intentionally delay responses or return selected failure statuses. Do not test retries against an endpoint that creates real orders or other side effects.
+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. Keep automatic retries disabled unless the order API supports an idempotency key or another form of duplicate protection.
+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), explicitly disables retries, and adds messages for the caller.
+The following configuration applies a 20-second timeout to the [coffee-order quickstart](/tools/api-request/quickstart) and adds messages for the caller.
 
 <Tabs>
   <Tab title="Dashboard">
@@ -84,11 +84,6 @@ The following configuration applies a 20-second timeout to the [coffee-order qui
       --header "Content-Type: application/json" \
       --data '{
         "timeoutSeconds": 20,
-        "backoffPlan": {
-          "type": "fixed",
-          "maxRetries": 0,
-          "baseDelaySeconds": 1
-        },
         "messages": [
           {
             "type": "request-start",
@@ -109,67 +104,37 @@ The following configuration applies a 20-second timeout to the [coffee-order qui
       }'
     ```
 
-    This explicitly keeps retries disabled for the order-creation request. Retrying this `POST` could create two orders when the first request succeeds but its response is lost or delayed.
+    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.
   </Tab>
 </Tabs>
 
-<Note>
-If you omit `backoffPlan`, the request is not retried. Setting `maxRetries` to `0` makes that choice explicit in the example.
-</Note>
+## 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.
 
-## Decide whether to retry
+To confirm how many requests reached your API, check the destination endpoint's logs.
 
-Retries are most useful for temporary failures on requests that are safe to repeat.
+## Retry through a service you control
 
-| Scenario | Retry guidance |
+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 |
 | --- | --- |
-| Read data with `GET` | Retry transient failures when a slightly longer wait is acceptable. |
-| Replace an existing resource with an idempotent `PUT` | Retry only when the destination API guarantees that repeating the same request has the same effect. |
-| Create an order, charge a card, send a message, or book an appointment | Do not retry unless the destination API provides idempotency or duplicate protection. |
-| `400`, `401`, `403`, or `404` response | Do not retry automatically. The request, credentials, permissions, or resource must change first. |
-| Rate limit or temporary server failure | Consider a small retry limit with exponential backoff for a safe request. |
+| 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 enable retries only because an endpoint sometimes fails. First decide whether repeating the request can duplicate work or create another side effect.
+Do not ask the assistant to repeat a state-changing request after a timeout until your service can determine whether the first request completed.
 </Warning>
 
-## Configure retries for a safe request
-
-A backoff plan controls how Vapi spaces retry attempts after a non-success response:
-
-- `fixed` waits the same amount between attempts.
-- `exponential` increases the delay after each attempt.
-- `maxRetries` is the number of retries after the original request and accepts values from 0 to 10.
-- `baseDelaySeconds` accepts values from 0 to 10 seconds.
-- `excludedStatusCodes` lists response codes that must not be retried. Without exclusions, non-2xx responses are retryable.
-
-The cURL request below uses the [Create Tool endpoint](/api-reference/tools/create) to create a separate `checkServiceStatus` `GET` tool. It makes one original request and allows at most two retries. Replace `https://api.example.com/status` with a status endpoint you control.
-
-The Dashboard can configure this tool's name, description, URL, and method, but not its backoff plan. The following cURL request creates the complete tool through the API:
-
-```bash
-curl --request POST \
-  --url https://api.vapi.ai/tool \
-  --header "Authorization: Bearer $VAPI_API_KEY" \
-  --header "Content-Type: application/json" \
-  --data '{
-    "type": "apiRequest",
-    "name": "checkServiceStatus",
-    "description": "Checks the current service status. Use when the caller asks whether the service is available.",
-    "method": "GET",
-    "url": "https://api.example.com/status",
-    "timeoutSeconds": 10,
-    "backoffPlan": {
-      "type": "exponential",
-      "maxRetries": 2,
-      "baseDelaySeconds": 1,
-      "excludedStatusCodes": [400, 401, 403, 404]
-    }
-  }'
-```
-
-Keep the retry limit small for voice calls. Every additional attempt can extend the silence or filler time before the assistant receives a final result.
-
 ## Keep the caller informed
 
 Tool messages control what the caller hears while a request is running and after it finishes.

fern/tools/api-request/response-handling.mdx

@@ -44,7 +44,7 @@ Return a non-2xx status when the action does not complete. Keep the error body m
 }
 ```
 
-The API Request Tool treats a non-2xx response as a failed request. If a backoff plan is configured, the status code also determines whether the request is eligible for a retry. See [Handle latency and retries](/tools/api-request/reliability) before enabling retries.
+The API Request Tool treats a non-2xx response as a failed request. It does not automatically retry the request, even if `backoffPlan` is configured. See [Handle latency and retries](/tools/api-request/reliability) for safe ways to handle failures.
 
 <Note>
 Calculate prices, availability, permissions, and other authoritative values on your server. Do not ask the model to calculate or invent them.