Error Handling

Quiver uses Splode for structured error classification. Every error carries a :class that tells you how to react.

Error Classes

Pattern Matching on Errors

case Quiver.new(:get, url) |> Quiver.request(:http_client) do
  {:ok, response} ->
    process(response)

  {:error, %Quiver.Error{class: :transient} = error} ->
    Logger.warning("Transient error: #{Exception.message(error)}")
    retry(url)

  {:error, %Quiver.Error{class: :invalid} = error} ->
    Logger.error("Invalid request: #{Exception.message(error)}")
    {:error, :bad_request}

  {:error, %Quiver.Error{class: :unrecoverable} = error} ->
    Logger.error("Unrecoverable: #{Exception.message(error)}")
    {:error, :service_unavailable}
end

You can also match on specific error types:

case result do
  {:error, %Quiver.Error.Timeout{}} ->
    # Handle timeout specifically

  {:error, %Quiver.Error.TLSVerificationFailed{host: host}} ->
    Logger.error("Certificate verification failed for #{host}")

  {:error, _} ->
    # Generic fallback
end

Retry Strategies by Class

Transient errors -- retry with backoff

Transient errors are safe to retry. Use exponential backoff:

defp request_with_retry(request, name, retries \\ 3, delay \\ 100)
defp request_with_retry(_request, _name, 0, _delay), do: {:error, :max_retries}

defp request_with_retry(request, name, retries, delay) do
  case Quiver.request(request, name) do
    {:ok, response} ->
      {:ok, response}

    {:error, %Quiver.Error{class: :transient}} ->
      Process.sleep(delay)
      request_with_retry(request, name, retries - 1, delay * 2)

    {:error, _} = error ->
      error
  end
end

Invalid errors -- fix and retry

Invalid errors indicate a problem with the request. Don't retry without changing the input.

Unrecoverable errors -- escalate

Unrecoverable errors signal infrastructure problems (TLS misconfiguration, protocol violations). Log them, alert your monitoring system, and investigate.

Error Reference

Transient Errors

Invalid Errors

Unrecoverable Errors