ML-21: Classify API errors as transient vs permanent

lib/open_ai/api.ex

@@ -1,13 +1,23 @@
 defmodule OpenAI.API do
   @moduledoc """
   Low-level HTTP client for the OpenAI API (chat completions, streaming responses, embeddings).
+
+  HTTP errors are returned as `OpenAI.API.ErrorResponse` structs, which classify
+  rate-limit failures (retryable) separately from billing-quota failures
+  (`insufficient_quota` — non-retryable) despite both using HTTP 429.
+
+  Mid-stream failures in `chat_stream/6` come from parsed SSE event payloads
+  rather than HTTP responses and remain as message strings passed through the
+  stream callback plumbing.
   """
 
+  alias OpenAI.API.ErrorResponse
   alias Req.Request
 
   require Logger
 
-  @spec gpt(OpenAI.Completion.t(), OpenAI.Config.t()) :: {:ok, map()} | {:error, term()}
+  @spec gpt(OpenAI.Completion.t(), OpenAI.Config.t()) ::
+          {:ok, map()} | {:error, ErrorResponse.t() | Exception.t()}
   def gpt(completion, config) do
     case config
          |> new_request()
@@ -27,17 +37,17 @@ defmodule OpenAI.API do
         content = get_in(body, ["choices", Access.at(0), "message", "content"])
         JSON.decode(content)
 
-      {:ok, %{body: body}} ->
-        {:error, "OpenAI API error: #{inspect(body)}"}
+      {:ok, response} ->
+        {:error, ErrorResponse.from_response(response)}
 
       {:error, exception} ->
-        {:error, "Connection error: #{Exception.message(exception)}"}
+        {:error, exception}
     end
   end
 
   @spec chat_stream([map()], String.t(), String.t(), float(), OpenAI.Config.t(), (String.t() ->
                                                                                     any())) ::
-          :ok | {:error, String.t()}
+          :ok | {:error, ErrorResponse.t() | Exception.t() | String.t()}
   def chat_stream(messages, instructions, model, temperature, config, cb) do
     config
     |> new_request()
@@ -86,33 +96,35 @@ defmodule OpenAI.API do
           :ok
         end
 
-      {:ok, %{body: body}} ->
-        {:error, "OpenAI API error: #{inspect(body)}"}
+      {:ok, response} ->
+        {:error, ErrorResponse.from_response(response)}
 
       {:error, exception} ->
-        {:error, "Connection error: #{Exception.message(exception)}"}
+        {:error, exception}
     end
   end
 
-  @spec get_embeddings(String.t(), OpenAI.Config.t()) :: {:ok, [float()]} | {:error, term()}
+  @spec get_embeddings(String.t(), OpenAI.Config.t()) ::
+          {:ok, [float()]} | {:error, ErrorResponse.t() | Exception.t()}
   def get_embeddings(text, config) do
-    resp =
-      config
-      |> new_request()
-      |> Req.merge(
-        url: "/v1/embeddings",
-        json: %{
-          input: text,
-          model: "text-embedding-3-small"
-        }
-      )
-      |> Req.post!()
+    case config
+         |> new_request()
+         |> Req.merge(
+           url: "/v1/embeddings",
+           json: %{
+             input: text,
+             model: "text-embedding-3-small"
+           }
+         )
+         |> Req.post() do
+      {:ok, %{status: 200, body: body}} ->
+        {:ok, get_in(body, ["data", Access.at(0), "embedding"])}
 
-    if resp.status == 200 do
-      embeddings = get_in(resp.body, ["data", Access.at(0), "embedding"])
-      {:ok, embeddings}
-    else
-      {:error, resp.body}
+      {:ok, response} ->
+        {:error, ErrorResponse.from_response(response)}
+
+      {:error, exception} ->
+        {:error, exception}
     end
   end
 

lib/open_ai/api/error_response.ex

@@ -0,0 +1,83 @@
+defmodule OpenAI.API.ErrorResponse do
+  @moduledoc """
+  Structured error response for OpenAI API calls.
+
+  OpenAI uses HTTP status codes as the primary classifier, with one critical
+  body-peek exception:
+
+    * HTTP **429** covers both `code: "rate_limit_exceeded"` (transient — retry)
+      and `code: "insufficient_quota"` (permanent — billing failure, cancel).
+      `from_response/1` reads `error.code` to disambiguate.
+
+  Error body shape (non-streaming):
+
+      %{"error" => %{"message" => ..., "type" => ..., "code" => ..., "param" => ...}}
+
+  Mid-stream SSE `error` / `response.failed` events are handled separately in
+  `OpenAI.API.chat_stream/6` and do not flow through this module.
+  """
+
+  @behaviour MusicLibrary.ErrorResponse
+
+  alias MusicLibrary.HttpError
+
+  @type t :: %__MODULE__{
+          status: integer() | nil,
+          code: String.t() | nil,
+          type: String.t() | nil,
+          message: String.t() | nil,
+          kind: HttpError.kind(),
+          body: term()
+        }
+
+  defstruct [:status, :code, :type, :message, :kind, :body]
+
+  @spec from_response(Req.Response.t() | map()) :: t()
+  def from_response(%{status: 429, body: %{"error" => %{"code" => "insufficient_quota"} = e}} = r) do
+    %__MODULE__{
+      status: 429,
+      code: "insufficient_quota",
+      type: e["type"],
+      message: e["message"],
+      kind: :auth_error,
+      body: r.body
+    }
+  end
+
+  def from_response(%{status: status, body: %{"error" => err} = body} = _response)
+      when is_map(err) do
+    %__MODULE__{
+      status: status,
+      code: err["code"],
+      type: err["type"],
+      message: err["message"],
+      kind: HttpError.default_kind(status),
+      body: body
+    }
+  end
+
+  def from_response(%{status: status, body: body} = _response) do
+    %__MODULE__{
+      status: status,
+      code: nil,
+      type: nil,
+      message: nil,
+      kind: HttpError.default_kind(status),
+      body: body
+    }
+  end
+
+  @impl MusicLibrary.ErrorResponse
+  @spec retryable?(t()) :: boolean()
+  def retryable?(%__MODULE__{kind: kind}) when kind in [:rate_limit, :server_error, :timeout],
+    do: true
+
+  def retryable?(%__MODULE__{}), do: false
+
+  @impl MusicLibrary.ErrorResponse
+  @spec retry_delay_seconds(t()) :: pos_integer()
+  def retry_delay_seconds(%__MODULE__{kind: :rate_limit}), do: 60
+  def retry_delay_seconds(%__MODULE__{kind: :server_error}), do: 30
+  def retry_delay_seconds(%__MODULE__{kind: :timeout}), do: 10
+  def retry_delay_seconds(%__MODULE__{}), do: 30
+end