From ae1d6e375e039e1008d492f02025fb6624461a98 Mon Sep 17 00:00:00 2001 From: Aakash Kattelu Date: Mon, 3 Aug 2026 17:40:46 -0400 Subject: [PATCH] docs: document provider_params.timeout load-time validation and gotchas Co-Authored-By: Claude Fable 5 --- docs/v3/contributing/configuration.mdx | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/docs/v3/contributing/configuration.mdx b/docs/v3/contributing/configuration.mdx index 0c073a56..384c7841 100644 --- a/docs/v3/contributing/configuration.mdx +++ b/docs/v3/contributing/configuration.mdx @@ -197,6 +197,21 @@ Because provider params live on each model config, background workers such as the Deriver and Dreamer can use longer request timeouts while synchronous chat paths keep tighter defaults. +`timeout` gotchas: + +- The value is validated **at config load**: it must coerce to a positive, + finite number of seconds (numbers or numeric strings like `"3600"`), or the + process refuses to start with an error naming the offending config path. + This applies to both the primary model config and its `fallback.overrides`. +- The unit is always **seconds**, regardless of transport. OpenAI and + Anthropic receive it as the SDK's `timeout` kwarg; Gemini has no such + kwarg, so Honcho converts it to milliseconds on `http_options.timeout`. +- When unset, nothing is forwarded and each SDK's default applies — adding + this key is opt-in and changes no existing behavior. +- A too-tight timeout doesn't fail once: the aborted request goes through the + normal retry/fallback chain before the caller sees an error, so the + observed latency is several multiples of the timeout. + #### Transport passthrough keys Three keys inside `provider_params` are recognized as request-level escape hatches and forwarded to the underlying transport. Where a transport actually validates and merges one of these keys, its value must be a mapping — a non-mapping value raises a configuration error (see the per-transport behavior below; a key a transport ignores is not validated):