[BUG] Unhandled OpenAI Cloudeflare 520 #606
Description
Basic checks
- I searched existing issues - this hasn't been reported
- I can reproduce this consistently
- This is a RubyLLM bug, not my application code
What's broken?
We occasionally (two instances over something like two months) see what appears to be a 520 status code (guessing based on the HTML payload) when using OpenAI that is returned from Cloudelfare.
Example
vendor/bundle/ruby/3.4.0/gems/ruby_llm-1.11.0/lib/ruby_llm/error.rb:69:in `RubyLLM::ErrorMiddleware.parse_error': <!DOCTYPE html>
<!--[if lt IE 7]> <html class="no-js ie6 oldie" lang="en-US"> <![endif]-->
<!--[if IE 7]> <html class="no-js ie7 oldie" lang="en-US"> <![endif]-->
<!--[if IE 8]> <html class="no-js ie8 oldie" lang="en-US"> <![endif]-->
<!--[if gt IE 8]><!--> <html class="no-js" lang="en-US"> <!--<![endif]-->
<head>
<title>api.openai.com | 520: Web server is returning an unknown error</title>
<meta charset="UTF-8" />
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta name="robots" content="noindex, nofollow" />
<meta name="viewport" content="width=device-width,initial-scale=1" />
<link rel="stylesheet" id="cf_styles-css" href="/cdn-cgi/styles/main.css" />
</head>
<body>
<div id="cf-wrapper">
<div id="cf-error-details" class="p-0">
<header class="mx-auto pt-10 lg:pt-6 lg:px-8 w-240 lg:w-full mb-8">
<h1 class="inline-block sm:block sm:mb-2 font-light text-60 lg:text-4xl text-black-dark leading-tight mr-2">
<span class="inline-block">Web server is returning an unknown error</span>
<span class="code-label">Error code 520</span>
</h1>
<div>
Visit <a href="https://www.cloudflare.com/5xx-error-landing?utm_source=errorcode_520&utm_campaign=api.openai.com" target="_blank" rel="noopener noreferrer">cloudflare.com</a> for more information.
</div>
<div class="mt-3">2026-02-13 21:43:53 UTC</div>
How to reproduce
N/A - Intermittent
Expected behavior
Rather than throw RubyLLM::Error, throw a specific error class, maybe RubyLLM::CloudflareError or something more generic?
https://github.com/crmne/ruby_llm/blob/main/lib/ruby_llm/error.rb
I'm happy to open a PR but first wanted to both confirm this seems reasonable to wrap in a specific error so downstream applications can handle as needed?
And if so, what the best name might be if not RubyLLM::CloudflareError?
What actually happened
Generic RubyLLM::Error
Environment
ruby-3.4.7ruby_llm (1.11.0)- OpenAI