llm_wire/error

Describes why a call failed (Error) or could not be prepared (PrepareError).

A failed call returns an llm_wire.Failure, whose error field is an Error. Most callers decide with llm_wire.advise(failure) and log with llm_wire.describe_failure(failure); branch on Error only for the cases you handle differently:

case failure.error {
  error.InvalidOutput(raw_output:, failure: reason) -> store(raw_output, reason)
  error.Http(http_failure) -> log(http_error.describe(http_failure))
  _ -> log(llm_wire.describe_failure(failure))
}

kind(error) is a closed classification that never gains variants, for a caller that wants an exhaustive case; name(error) is a stable identifier for logs and stored records.

Http carries HTTP Gun’s opaque Failure, so http_gun/error.kind, is_retryable, status and headers apply to it directly.

prepare is pure, so its PrepareError never describes the network: it names the setting, request field, schema or tool result that must change. Error, PrepareError and their detail types may gain variants in a minor release; match them with a _ arm. Strings in variants are diagnostics for people; branch on the variants, never on the text.

Types

Error

</>

Why an executed call failed.

pub type Error {
  Http(failure: error.Failure)
  Status(
    code: Int,
    body: String,
    retry_after: option.Option(duration.Duration),
  )
  Provider(code: option.Option(String), message: String)
  Protocol(detail: String)
  LimitExceeded(
    limit: limit.Limit,
    limit_value: Int,
    measured: Int,
  )
  DeadlineExceeded(timeout: Timeout)
  Cancelled
  InvalidOutput(raw_output: String, failure: ValueFailure)
  Stopped
  ContentFiltered(stage: FilterStage, reason: String)
}

Constructors

```
Http(failure: error.Failure)
```
The HTTP exchange failed. The opaque Failure keeps HTTP Gun’s Kind, evidence, status and response headers.
```
Status(
  code: Int,
  body: String,
  retry_after: option.Option(duration.Duration),
)
```
The provider answered with a status other than 200. body is at most limit.ErrorBodyBytes; retry_after comes from a Retry-After header in seconds or as an HTTP date.

Provider(code: option.Option(String), message: String)

The provider reported an error inside the stream.

```
Protocol(detail: String)
```
The stream broke the provider’s protocol. detail is diagnostic.

LimitExceeded(
  limit: limit.Limit,
  limit_value: Int,
  measured: Int,
)

A bound was exceeded. limit names the llm_wire.with_limit setting that raises it.

```
DeadlineExceeded(timeout: Timeout)
```
A timer expired; timeout names the llm_wire.with_*_timeout setter.
```
Cancelled
```
The caller closed the stream or cancelled the call.

InvalidOutput(raw_output: String, failure: ValueFailure)

The model’s final text is not valid structured output.

```
Stopped
```
The process that owned the call stopped before a result, for example because it could not start.
```
ContentFiltered(stage: FilterStage, reason: String)
```
The provider’s safety system blocked the prompt or stopped the output. reason is the provider’s own value: OpenAI’s incomplete_details.reason ("content_filter"), Anthropic’s stop_reason ("refusal"), Gemini’s finishReason ("SAFETY", "RECITATION", "BLOCKLIST", "PROHIBITED_CONTENT", "SPII", "IMAGE_SAFETY", "IMAGE_PROHIBITED_CONTENT") or promptFeedback.blockReason. Retrying the same request will not help. A model that declines in its own words is the outcome llm_wire.Refused, not this error.

FilterStage

</>

Where a provider’s content filter stopped a call.

pub type FilterStage {
  InPrompt
  InOutput
}

Constructors

```
InPrompt
```
The prompt was blocked before generation (Gemini’s promptFeedback.blockReason).
```
InOutput
```
Generation stopped after it started.

Kind

</>

A small, closed classification of Error. Unlike Error, it gains no variants in a minor release, so a case on it needs no _ arm. Branch on it, decide retries with llm_wire.advise, and read Error for detail.

pub type Kind {
  Transport
  ProviderError
  ContentPolicy
  UnusableResponse
  OverLimit
  Ended
}

Constructors

```
Transport
```
Http or DeadlineExceeded: the exchange did not complete.
```
ProviderError
```
Status or Provider: the provider answered with an error.
```
ContentPolicy
```
ContentFiltered: the provider’s safety system stopped the call; the prompt must change.
```
UnusableResponse
```
Protocol or InvalidOutput: the response arrived but cannot be used.
```
OverLimit
```
LimitExceeded: a bound set with llm_wire.with_limit stopped the call.
```
Ended
```
Cancelled or Stopped: the call ended locally before a result.

PrepareError

</>

Why llm_wire.prepare refused a configuration or request.

pub type PrepareError {
  InvalidSetting(setting: Setting, reason: String)
  InvalidRequest(problem: RequestProblem)
  UnsupportedSchema(location: SchemaLocation, reason: String)
  ToolResultMismatch(call_id: String, problem: ResultProblem)
  RequestTooLarge(
    limit: limit.Limit,
    limit_value: Int,
    measured: Int,
  )
}

Constructors

```
InvalidSetting(setting: Setting, reason: String)
```
A configuration value is invalid. reason is diagnostic.
```
InvalidRequest(problem: RequestProblem)
```
A request field or message is invalid for this provider.

UnsupportedSchema(location: SchemaLocation, reason: String)

A tool or output schema cannot be sent to this provider.

```
ToolResultMismatch(call_id: String, problem: ResultProblem)
```
Tool results do not match the calls of the assistant turn before them.

RequestTooLarge(
  limit: limit.Limit,
  limit_value: Int,
  measured: Int,
)

The request exceeds a bound before it is sent.

RequestProblem

</>

What is wrong with a request.

pub type RequestProblem {
  InvalidClassificationContent(reason: String)
  ClassificationQuestionUnsupported(question_id: String)
  MaxTokensNotPositive
  TemperatureOutOfRange
  TopPOutOfRange
  EmptyPromptCache
  PromptCacheUnsupported
  StopSequencesUnsupported
  TooManyStopSequences(maximum: Int)
  ImageUrlUnsupported
  DuplicateToolName(name: String)
  InvalidCallId(call_id: String)
  InvalidToolName(name: String)
  TurnFromOtherProvider
  InvalidProviderData(reason: String)
}

Constructors

```
InvalidClassificationContent(reason: String)
```
Classification state must be text, an object or an array within JSON limits.
```
ClassificationQuestionUnsupported(question_id: String)
```
The classification wire cannot provide the requested question evidence.
```
MaxTokensNotPositive
```
```
TemperatureOutOfRange
```
```
TopPOutOfRange
```
```
EmptyPromptCache
```
A prompt cache key or cached-content name is empty.
```
PromptCacheUnsupported
```
The prompt cache reference belongs to another provider.
```
StopSequencesUnsupported
```
```
TooManyStopSequences(maximum: Int)
```
```
ImageUrlUnsupported
```
This provider refuses remote image URLs; send inline image data.
```
DuplicateToolName(name: String)
```
```
InvalidCallId(call_id: String)
```
A call in the conversation has an empty id or a duplicate id.
```
InvalidToolName(name: String)
```
A call in the conversation names a tool outside the tool-name grammar.
```
TurnFromOtherProvider
```
An assistant turn came from a different provider than this request.
```
InvalidProviderData(reason: String)
```
An assistant turn’s provider data is missing, malformed or disagrees with its text and calls. reason is diagnostic.

ResultProblem

</>

How tool results disagree with the calls they answer.

pub type ResultProblem {
  MissingResult
  DuplicateResult
  UnknownCall
  NoPrecedingCalls
}

Constructors

```
MissingResult
```
```
DuplicateResult
```
```
UnknownCall
```
The result answers no call of the preceding assistant turn.
```
NoPrecedingCalls
```
The result follows no assistant turn with calls.

SchemaLocation

</>

Where an unsupported schema was found.

pub type SchemaLocation {
  ToolInput(tool: String)
  Output
}

Constructors

```
ToolInput(tool: String)
```
```
Output
```

Setting

</>

A configuration value InvalidSetting names.

pub type Setting {
  ApiKey
  Model
  Endpoint
  Header
  OutputName
  LimitSetting(limit: limit.Limit)
  TimeoutSetting(timeout: Timeout)
}

Constructors

```
ApiKey
```
```
Model
```
```
Endpoint
```
```
Header
```
```
OutputName
```
```
LimitSetting(limit: limit.Limit)
```
```
TimeoutSetting(timeout: Timeout)
```

Timeout

</>

The three timers of a call.

pub type Timeout {
  WholeCall
  FirstToken
  IdleGap
}

Constructors

```
WholeCall
```
From the start of execution to the final event. Default 600 s.
```
FirstToken
```
From the start of execution to the first progress event, covering admission, the response head and hidden reasoning. Default 180 s.
```
IdleGap
```
The longest gap between provider events after the first progress event. Every event resets it, including tool-argument deltas and pings. Default 60 s.

ValueFailure

</>

Why a JSON value (structured output or tool arguments) was refused.

pub type ValueFailure {
  InvalidJson(value.ParseError)
  SchemaRejected(contract.ValidationError)
  DecodeRejected(codec.DecodeError)
}

Constructors

```
InvalidJson(value.ParseError)
```
The text is not JSON within the parser’s bounds.

SchemaRejected(contract.ValidationError)

The JSON does not satisfy the schema.

```
DecodeRejected(codec.DecodeError)
```
The JSON satisfies the schema but the codec refused it.

Values

describe

</>

pub fn describe(error: Error) -> String

A one-line description for logs.

describe_prepare_error

</>

pub fn describe_prepare_error(error: PrepareError) -> String

A one-line description of a preparation error.

describe_value_failure

</>

pub fn describe_value_failure(failure: ValueFailure) -> String

A one-line description of a refused JSON value.

kind

</>

pub fn kind(error: Error) -> Kind

The closed classification of error.

kind_name

</>

pub fn kind_name(kind: Kind) -> String

A stable snake_case name, such as "content_policy".

name

</>

pub fn name(error: Error) -> String

A stable identifier for logs and stored records, such as "limit_exceeded.total_text_bytes" or "deadline_exceeded.first_token".

timeout_name

</>

pub fn timeout_name(timeout: Timeout) -> String

A stable snake_case name: "whole_call", "first_token" or "idle_gap".