Guides  /  Durability and failure

What happens when a model call hangs instead of failing?

Answer

A hung call holds its slot and returns nothing. The run waits and the resources it reserved stay reserved. No error arrives to trigger the handling that a failure would.

A deadline converts the hang into a failure the system can act on. The runtime cancels the call, releases the slot, and the run retries, routes to another model, or escalates.

The mechanism

A hang is worse than an error.

An error arrives quickly and carries information. Retry logic runs, a fallback fires, and the slot is returned. A hang produces none of that. The call stays open and the caller stays blocked. From outside the system looks healthy, because nothing has failed yet.

Under load the effect compounds. Each hung call holds capacity that queued work needs, the queue grows, and the growth produces more calls that hang for the same reason.

What a deadline needs to cover

The timeout on the call is not the whole answer.

The callA bound on how long a single model or tool call may run before the runtime cancels it.
The stepA bound on the step containing the call, so a chain of retries inside it cannot outlive the budget.
The runA bound on the whole run, so an agent that keeps finding more to do is stopped by policy rather than by an operator.
The releaseCancellation returns the slot. A deadline that fires without freeing the resource moves the problem instead of solving it.
What this changes

Capacity stops draining silently.

Backpressure and deadlines solve adjacent halves of the same problem. Backpressure stops a fast producer from overwhelming a slow consumer. Deadlines stop a consumer that has stopped responding from holding capacity indefinitely.

Backpressure and deadlines are properties of the runtime executing the work. A library wrapped around the call can time out its own wait and cannot release what the runtime is holding.

Questions

Related questions.

What deadline is right?

Short enough that a hung call does not consume the budget of the run containing it, and long enough to let a slow response finish. The figure comes from the observed latency distribution.

Should the run retry after a deadline?

A retry is safe when the runtime recorded whether the call executed. Without that record the retry may repeat an action that already happened.

Does routing to another model help?

A deadline that fires on one provider can route the retry to another. The policy that chooses the model already exists, so the failure becomes a routing decision.

How is this different from a health check?

A health check asks whether the provider is up. A deadline asks whether this call is still worth waiting for. A provider can pass its health check while individual calls hang.

On Akka. Timeouts, cancellation and flow control are described in the Akka SDK documentation.