class RubyLLM::Error

Error is the base class for provider-operation errors raised by RubyLLM, including API, network, capability, and provider response-shape failures. When an HTTP response is available, it wraps that response and normalizes the message across providers. When the provider refuses a conversation, request_shape describes what it was sent. Subclasses map common HTTP status codes: BadRequestError (400), UnauthorizedError (401), PaymentRequiredError (402), ForbiddenError (403), RateLimitError (429), ServerError (500), ServiceUnavailableError (502 to 504), and OverloadedError (529).

begin
  RubyLLM.chat.ask "Translate 'hello' to French."
rescue RubyLLM::RateLimitError
  puts "Rate limit hit. Please wait a moment."
rescue RubyLLM::Error => e
  puts "API error: #{e.message}"
  puts e.response&.status
end

Local setup and programming errors, such as ConfigurationError and ModelNotFoundError, inherit from StandardError directly and are not caught by rescuing Error.

Attributes

response [R]

The HTTP response that caused the error, or nil when none is available. Its status and body carry the provider’s reply.

Public Class Methods

new (message = nil, response: nil)

Source

# File lib/ruby_llm/error.rb, line 44
def initialize(message = nil, response: nil)
  @response = response
  super(message || response&.body || self.class.default_message)
end

Creates an error with message. Pass response: to attach the HTTP response; its body supplies the message when message is nil.

Calls superclass method

Public Instance Methods

request_shape ()

Source

# File lib/ruby_llm/error.rb, line 60
def request_shape
  return unless request_protocol
  return @request_shape if defined?(@request_shape)

  @request_shape = request_protocol.request_shape(request_payload)
end

Returns a RequestShape describing the conversation request the error answered: each turn’s parts and their sizes, never their contents, and the problems providers are known to refuse. Returns nil for errors raised before a request goes out, such as an unsupported attachment, and for operations that send no conversation, such as embeddings.

rescue RubyLLM::BadRequestError => e
  Rails.logger.error("#{e.message}\n#{e.request_shape}")
  Rails.error.report(e, context: { request_shape: e.request_shape&.to_h })