GitHub

Result Types

Abstract and concrete types for handling API call outcomes. All result types are subtypes of LLMRequestResponse.

Abstract Type

Chat Completions Results

UniLM.LLMSuccess — Type
LLMSuccess(; message, self, usage=nothing, sse_dropped=0)

Successful Chat Completions API response.

Fields

  • message::Message: The assistant's reply message.
  • self::Chat: The updated Chat object (with the new message appended if history=true).
  • usage::Union{TokenUsage, Nothing}: Token usage statistics from the API.
  • sse_dropped::Int: Undecodable SSE data: payloads dropped while assembling this streamed turn — 0 for a non-streamed call, and for a clean stream. Non-zero means the turn was built from an incomplete wire.
source
UniLM.LLMFailure — Type
LLMFailure(; response, status, self, request_id=nothing, sse_dropped=0)

HTTP-level failure from the Chat Completions API. The server returned a non-200 status.

Fields

  • response::String: The raw response body.
  • status::Int: The HTTP status code.
  • self::Chat: The Chat object (unchanged).
  • request_id::Union{String, Nothing}: The HTTP request ID from headers, if available.
  • sse_dropped::Int: Undecodable SSE data: payloads dropped during a streamed attempt — 0 for a non-streamed call. On a truncated stream (HTTP 200, no terminal event) this is often the reason no message could be built.
source
UniLM.LLMCallError — Type
LLMCallError(; error, status=nothing, self, request_id=nothing, cause=nothing)

Exception-level error during a Chat Completions API call (network failure, JSON parse error, timeout, etc.).

Fields

  • error::String: The stringified exception.
  • status::Union{Int,Nothing}: HTTP status if available (nothing for timeouts — no fabricated statuses).
  • self::Chat: The Chat object (unchanged).
  • request_id::Union{String, Nothing}: The HTTP request ID from headers, if available.
  • cause::Union{Nothing,Exception}: The underlying typed exception when one exists (e.g. a UniLMTimeout carrying phase/elapsed/limit).
source

Pattern Matching

result = chatrequest!(chat)

if result isa LLMSuccess
    println(result.message.content)
    println(result.message.finish_reason)  # "stop"
elseif result isa LLMFailure
    @warn "HTTP $(result.status): $(result.response)"
elseif result isa LLMCallError
    @error "Call error: $(result.error)"
end

Result Helpers

Predicates and an accessor for consuming any result — success or failure:

UniLM.issuccess — Function
issuccess(r::LLMRequestResponse) -> Bool

true when r is a success result (any *Success type), false for every failure or call-error result. The generic method returns false; each concrete *Success result type gets its own true method (registered once every result type across the APIs is defined — see the bottom of UniLM.jl).

result = chatrequest!(chat)
issuccess(result) ? println(text(result)) : @warn "call did not succeed"
source
UniLM.LLMResultError — Type
LLMResultError <: Exception

Thrown by text when it is called on a non-success Chat result (LLMFailure or LLMCallError). Carries the offending result. showerror prints only the status and a short (≤200-char) response excerpt — never the conversation, the service endpoint, or the API key.

source

text returns the assistant reply on a LLMSuccess (possibly nothing for a tool-calls-only turn) and throws an LLMResultError on a failure. Guard with issuccess / isfailure, or pattern-match the result type first:

result = chatrequest!(chat)
if issuccess(result)
    println(text(result))
else
    @warn "call did not succeed"
end

Responses API Results

See also the Responses API reference.

Pattern Matching

result = respond("Tell me a joke")

if result isa ResponseSuccess
    println(output_text(result))
    println(result.response.status)  # "completed"
elseif result isa ResponseFailure
    @warn "HTTP $(result.status)"
elseif result isa ResponseCallError
    @error result.error
end

Image Generation Results

See also the Images API reference.

Pattern Matching

result = generate_image("A robot writing Julia code")

if result isa ImageSuccess
    save_image(image_data(result)[1], "robot.png")
elseif result isa ImageFailure
    @warn "HTTP $(result.status): $(result.response)"
elseif result isa ImageCallError
    @error result.error
end

Type Hierarchy

All result types share the abstract parent LLMRequestResponse:

LLMRequestResponse   (abstract parent of every result type below)
│
├─ Chat Completions   LLMSuccess · LLMFailure · LLMCallError
├─ Responses API      ResponseSuccess · ResponseFailure · ResponseCallError
├─ Embeddings         EmbeddingSuccess · EmbeddingFailure · EmbeddingCallError
├─ Image Generation   ImageSuccess · ImageFailure · ImageCallError
├─ FIM Completion     FIMSuccess · FIMFailure · FIMCallError
├─ Files              FileSuccess · FileListSuccess · FileContentSuccess · FileDeleteSuccess · FileFailure · FileCallError
├─ Vector Stores      VectorStoreSuccess · VectorStoreListSuccess · VectorStoreFileSuccess · VectorStoreBatchSuccess · VectorStoreDeleteSuccess · VectorStoreFailure · VectorStoreCallError
├─ Conversations      ConversationSuccess · ConversationItemSuccess · ConversationItemListSuccess · ConversationDeleteSuccess · ConversationFailure · ConversationCallError
├─ Moderations        ModerationSuccess · ModerationFailure · ModerationCallError
├─ Audio              SpeechSuccess · TranscriptionSuccess · AudioFailure · AudioCallError
├─ Batch              BatchSuccess · BatchListSuccess · BatchFailure · BatchCallError
├─ Fine-tuning        FineTuningSuccess · FineTuningListSuccess · FineTuningFailure · FineTuningCallError
├─ Containers         ContainerSuccess · ContainerListSuccess · ContainerDeleteSuccess · ContainerFailure · ContainerCallError
├─ Uploads            UploadSuccess · UploadPartSuccess · UploadFailure · UploadCallError
├─ Videos             VideoSuccess · VideoListSuccess · VideoContentSuccess · VideoFailure · VideoCallError
└─ Realtime           RealtimeSecretSuccess · RealtimeFailure · RealtimeCallError

Every *Success wraps a parsed response object; every *Failure carries the HTTP status and body; every *CallError wraps a transport/exception. Pattern-match on the family you called (see each API-reference page for the concrete fields).