From 8daead622078e2dd3d96e7a802db6bd07e635bd8 Mon Sep 17 00:00:00 2001
From: Steve Smtih <stephen@vapi.ai>
Date: Mon, 5 Oct 2026 05:08:51 -0700
Subject: [PATCH] docs: clarify timeout-vs-retry behavior and retry headers for
 API Request Tool

---
 fern/tools/api-request/reliability.mdx | 16 +++++++++++++++-
 1 file changed, 15 insertions(+), 1 deletion(-)

diff --git a/fern/tools/api-request/reliability.mdx b/fern/tools/api-request/reliability.mdx
index b4dd5b1ed..c12acd3d8 100644
--- a/fern/tools/api-request/reliability.mdx
+++ b/fern/tools/api-request/reliability.mdx
@@ -168,7 +168,21 @@ curl --request POST \
   }'
 ```
 
-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 retry limit small for voice calls. Every additional attempt can extend the silence or filler time before the assistant returns a final result.
+
+## Timeouts versus retries
+
+`excludedStatusCodes` and the "non-2xx responses are retryable" rule above both describe a request that reaches your endpoint and gets an HTTP response back. A request that never gets a response before `timeoutSeconds` elapses is a different failure mode, and whether that counts as a retryable attempt under `backoffPlan` is not yet documented here.
+
+<Note>
+If your tool depends on exactly when a timed-out request retries, verify the behavior for your `backoffPlan` configuration against a non-production endpoint before relying on it, or confirm with [Vapi support](https://help.vapi.ai).
+</Note>
+
+<!-- TODO (docs team): confirm with engineering whether a `timeoutSeconds` timeout (no response received) is treated as a retryable failure under `backoffPlan`, the same way an excluded or non-2xx HTTP response is, and replace this section with the confirmed behavior. -->
+
+To see what Vapi actually sent and received on an attempt, including the non-sensitive request headers, open the delivery in [Webhook logs](/observability/logs/webhook-logs). Webhook logs record each delivery's request and response, but do not currently document whether a retry attempt carries different headers than the original request.
+
+<!-- TODO (docs team): confirm with engineering whether backoffPlan retry attempts add or change any request headers (e.g. a retry-attempt or idempotency header) compared to the original request, and document the answer here. -->
 
 ## Keep the caller informed