[FEATURE] Surface specific error message

[adrianthedev]

Scope check

• This is core LLM communication (not application logic)
• This benefits most users (not just my use case)
• This can't be solved in application code with current RubyLLM
• I read the Contributing Guide

Due diligence

• I searched existing issues
• I checked the documentation

What problem does this solve?

I wanted to use Open AI GPT and Anthropic's Haiku. For the same prompt I would get back a proper response from OpenAI but Invalid request - please check your input from Anthropic.

After a bit of digging and turning on debugging, I found this message deeper.

Accumulating error chunk: {"type":"error","error":{"type":"invalid_request_error","message":"Your credit balance is too low to access the Anthropic API. Please go to Plans & Billing to upgrade or purchase credits."},"request_id":"..."}

So the error reason is there but needs to be resurfaced.

Proposed solution

Dig in the specific response and surface the actual error.

Why this belongs in RubyLLM

It's the way RubyLLM handles responses.

[adrianthedev]

I failed to run the tests and can't submit a PR 🫣
But I found the issue (I think).

When a streaming request fails (e.g. 429 Too Many Requests, 401 Unauthorized), the raised error has the wrong HTTP status code and an empty message.

Root cause

Two bugs interact:

1. Status fallback order is wrong in build_stream_error_response

parse_streaming_error always returns 500 — it never reads the real HTTP status. The old fallback order was:

error_status = status || env&.status || 500

So 500 (from parse_streaming_error) always wins over env.status (the real code from the server). It should be:

error_status = env&.status || status || 500

2. ErrorMiddleware#on_complete re-parses an empty body

When handle_parsed_error raises through parse_error, Faraday's streaming adapter swallows the exception and still fires on_complete. By that point the response body is empty (streaming already consumed it), so ErrorMiddleware runs parse_error again on an empty response — clobbering the proper error with a blank Error: message.

The fix is to stash the parsed error response on env before raising, and have ErrorMiddleware#on_complete prefer that over the now-empty response. Faraday 1's v1_on_data passes nil for env, so the write is guarded.

Fix

diff --git a/lib/ruby_llm/error.rb b/lib/ruby_llm/error.rb
index 04ec8c46..0fd6423b 100644
--- a/lib/ruby_llm/error.rb
+++ b/lib/ruby_llm/error.rb
@@ -45,7 +45,10 @@ module RubyLLM

     def call(env)
       @app.call(env).on_complete do |response|
-        self.class.parse_error(provider: @provider, response: response)
+        # For streaming errors, the adapter may swallow the on_data exception and still fire on_complete.
+        # By then response.body is empty, so fall back to what handle_parsed_error stored on env.
+        error_response = response[:streaming_error_response] || response
+        self.class.parse_error(provider: @provider, response: error_response)
       end
     end

diff --git a/lib/ruby_llm/streaming.rb b/lib/ruby_llm/streaming.rb
index a671f9cc..4ad580dc 100644
--- a/lib/ruby_llm/streaming.rb
+++ b/lib/ruby_llm/streaming.rb
@@ -123,6 +123,10 @@ module RubyLLM
     def handle_parsed_error(parsed_data, env)
       status, _message = parse_streaming_error(parsed_data.to_json)
       error_response = build_stream_error_response(parsed_data, env, status)
+      # Store on env so ErrorMiddleware#on_complete can use the parsed body and correct status.
+      # Without this, on_complete sees an empty body (streaming consumed it) and loses the message.
+      # Faraday 1 passes nil as env (see v1_on_data), so guard before writing.
+      env[:streaming_error_response] = error_response if env.respond_to?(:[]=)
       ErrorMiddleware.parse_error(provider: self, response: error_response)
     end

@@ -134,7 +138,7 @@ module RubyLLM
     end

     def build_stream_error_response(parsed_data, env, status)
-      error_status = status || env&.status || 500
+      error_status = env&.status || status || 500

       if faraday_1?
         Struct.new(:body, :status).new(parsed_data, error_status)

I can't run the test suite to submit this as a PR, but happy to if someone wants to pick it up or point to the relevant test files.