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
Providers often quote the request back in their error, so with Configuration#redact_error_messages the message carries only the HTTP status, the provider, and the provider’s error code. What the provider wrote stays on provider_message and its raw body on response_body.
Local setup and programming errors, such as ConfigurationError and ModelNotFoundError, inherit from StandardError directly and are not caught by rescuing Error.
Attributes
The provider’s code for the error, such as "invalid_request_error" or "INVALID_ARGUMENT", or nil when it gave none that reads like a code.
The slug of the provider that answered, such as "openai", or nil when it is not known.
What the provider wrote about the error, or nil when it wrote nothing RubyLLM could read. It can quote the request, so Configuration#redact_error_messages keeps it out of #message.
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
# File lib/ruby_llm/error.rb, line 69 def initialize(message = nil, response: nil, provider: nil, provider_message: nil, error_code: nil) @response = response @provider = provider @provider_message = provider_message @error_code = error_code if error_code.is_a?(Integer) || error_code.to_s.match?(ERROR_CODE) super(full_message_for(message) || self.class.default_message) end
Creates an error with message. Pass response: to attach the HTTP response, provider: to name the provider’s slug, error_code: for the provider’s code, kept only when it reads like one, and provider_message: for what the provider wrote, which follows message, or stands in for it when message is nil. Without either, the response body supplies the message.
Public Instance Methods
Source
# File lib/ruby_llm/error.rb, line 95 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 })
Source
# File lib/ruby_llm/error.rb, line 80 def response_body response&.body end
Returns the body of response, or nil without one. It can quote the request, so Configuration#redact_error_messages keeps it out of #message.