fix: detect low balance and prompt for top up

crates/goose-cli/src/session/output.rs

@@ -259,6 +259,25 @@ pub fn render_message(message: &Message, debug: bool) {
                         hide_thinking();
                         println!("\n{}", style(&notification.msg).yellow());
                     }
+                    SystemNotificationType::CreditsExhausted => {
+                        hide_thinking();
+                        println!("\n{}", style(&notification.msg).yellow());
+
+                        // If the provider supplied a top-up URL, try to open
+                        // the user's browser so they can add credits. Uses the
+                        // `webbrowser` crate (same cross-platform mechanism as
+                        // the Tetrate OAuth sign-up flow).
+                        if let Some(url) = notification
+                            .data
+                            .as_ref()
+                            .and_then(|d| d.get("top_up_url"))
+                            .and_then(|v| v.as_str())
+                        {
+                            if let Err(e) = webbrowser::open(url) {
+                                tracing::warn!("Failed to open browser for credits top-up: {}", e);
+                            }
+                        }
+                    }
                 }
             }
             _ => {

crates/goose/src/agents/agent.rs

@@ -1433,6 +1433,41 @@ impl Agent {
                                 }
                             }
                         }
+                        Err(ref provider_err @ ProviderError::CreditsExhausted { ref details, ref top_up_url }) => {
+                            crate::posthog::emit_error(provider_err.telemetry_type(), &provider_err.to_string());
+                            error!("Credits exhausted: {}", details);
+
+                            // Surface the error as a structured CreditsExhausted
+                            // notification so the UI layer (CLI, desktop app, API)
+                            // can decide how to present it — e.g. opening a browser,
+                            // showing a dialog, or returning it in a JSON response.
+                            let user_msg = if let Some(url) = top_up_url.as_deref() {
+                                format!(
+                                    "Your credits have been exhausted: {details}\n\n\
+                                     To add more credits, visit: {url}\n\n\
+                                     Once you've topped up, retry your last message to continue."
+                                )
+                            } else {
+                                format!(
+                                    "Your credits have been exhausted: {details}\n\n\
+                                     Please check your account with your provider to add more \
+                                     credits, then retry your last message to continue."
+                                )
+                            };
+
+                            let notification_data = serde_json::json!({
+                                "top_up_url": top_up_url,
+                            });
+
+                            yield AgentEvent::Message(
+                                Message::assistant().with_system_notification_with_data(
+                                    SystemNotificationType::CreditsExhausted,
+                                    user_msg,
+                                    notification_data,
+                                )
+                            );
+                            break;
+                        }
                         Err(ref provider_err) => {
                             crate::posthog::emit_error(provider_err.telemetry_type(), &provider_err.to_string());
                             error!("Error: {}", provider_err);

crates/goose/src/conversation/message.rs

@@ -164,6 +164,10 @@ pub struct FrontendToolRequest {
 pub enum SystemNotificationType {
     ThinkingMessage,
     InlineMessage,
+    /// Provider credits have been exhausted. The `data` field of the
+    /// notification may contain `{"top_up_url": "..."}` so the UI layer
+    /// can open the user's browser or show a clickable link.
+    CreditsExhausted,
 }
 
 #[derive(Debug, Clone, PartialEq, Serialize, Deserialize, ToSchema)]

crates/goose/src/providers/errors.rs

@@ -30,6 +30,13 @@ pub enum ProviderError {
 
     #[error("Unsupported operation: {0}")]
     NotImplemented(String),
+
+    #[error("Credits exhausted: {details}")]
+    CreditsExhausted {
+        details: String,
+        /// URL where the user can add more credits / top up
+        top_up_url: Option<String>,
+    },
 }
 
 impl ProviderError {
@@ -43,6 +50,7 @@ impl ProviderError {
             ProviderError::ExecutionError(_) => "execution",
             ProviderError::UsageError(_) => "usage",
             ProviderError::NotImplemented(_) => "not_implemented",
+            ProviderError::CreditsExhausted { .. } => "credits_exhausted",
         }
     }
 }

crates/goose/src/providers/openai_compatible.rs

@@ -219,6 +219,10 @@
         StatusCode::NOT_FOUND => {
             ProviderError::RequestFailed(format!("Resource not found (404): {}", extract_message()))
         }
+        StatusCode::PAYMENT_REQUIRED => ProviderError::CreditsExhausted {
+            details: extract_message(),
+            top_up_url: None,
+        },
         StatusCode::PAYLOAD_TOO_LARGE => ProviderError::ContextLengthExceeded(extract_message()),
         StatusCode::BAD_REQUEST => {
             let payload_str = extract_message();
@@ -294,3 +298,98 @@
         }
     }))
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use serde_json::json;
+
+    #[test]
+    fn http_402_maps_to_credits_exhausted() {
+        let payload = json!({
+            "error": {
+                "message": "Insufficient credits to complete this request"
+            }
+        });
+        let err = map_http_error_to_provider_error(
+            StatusCode::PAYMENT_REQUIRED,
+            Some(payload),
+        );
+        match err {
+            ProviderError::CreditsExhausted {
+                ref details,
+                ref top_up_url,
+            } => {
+                assert!(
+                    details.contains("Insufficient credits"),
+                    "Expected details to contain error message, got: {details}"
+                );
+                // Generic handler doesn't know the provider, so no URL
+                assert_eq!(*top_up_url, None);
+            }
+            other => panic!("Expected CreditsExhausted, got: {:?}", other),
+        }
+    }
+
+    #[test]
+    fn http_402_with_no_payload_maps_to_credits_exhausted() {
+        let err = map_http_error_to_provider_error(StatusCode::PAYMENT_REQUIRED, None);
+        assert!(
+            matches!(err, ProviderError::CreditsExhausted { .. }),
+            "Expected CreditsExhausted, got: {:?}",
+            err
+        );
+    }
+
+    #[test]
+    fn http_429_maps_to_rate_limit_not_credits() {
+        let payload = json!({
+            "error": {
+                "message": "Rate limit exceeded"
+            }
+        });
+        let err =
+            map_http_error_to_provider_error(StatusCode::TOO_MANY_REQUESTS, Some(payload));
+        assert!(
+            matches!(err, ProviderError::RateLimitExceeded { .. }),
+            "Expected RateLimitExceeded, got: {:?}",
+            err
+        );
+    }
+
+    #[test]
+    fn http_401_maps_to_authentication() {
+        let err = map_http_error_to_provider_error(StatusCode::UNAUTHORIZED, None);
+        assert!(
+            matches!(err, ProviderError::Authentication(_)),
+            "Expected Authentication, got: {:?}",
+            err
+        );
+    }
+
+    #[test]
+    fn http_400_with_context_length_maps_correctly() {
+        let payload = json!({
+            "error": {
+                "message": "This request exceeds the maximum context length"
+            }
+        });
+        let err = map_http_error_to_provider_error(StatusCode::BAD_REQUEST, Some(payload));
+        assert!(
+            matches!(err, ProviderError::ContextLengthExceeded(_)),
+            "Expected ContextLengthExceeded, got: {:?}",
+            err
+        );
+    }
+
+    #[test]
+    fn http_500_maps_to_server_error() {
+        let err =
+            map_http_error_to_provider_error(StatusCode::INTERNAL_SERVER_ERROR, None);
+        assert!(
+            matches!(err, ProviderError::ServerError(_)),
+            "Expected ServerError, got: {:?}",
+            err
+        );
+    }
+}