feat(api): return SVG fallback cards for user/API errors

Author: udaykiran243

api/main.py

@@ -6,6 +6,7 @@
 from config.settings import get_settings
 from generators import stats_card, lang_card, contrib_card, recent_activity_card, trophy_card, streak_card, repo_card, social_card, badge_generator
 from utils import github_api
+from utils.error_card import draw_error_card
 from utils.cache import cache_svg_response, get_cache_stats, clear_cache
 from utils.validators import (
     validate_date,
@@ -45,7 +46,7 @@ def generate_cached_svg(generator_func, *args, **kwargs):
     return generator_func(*args, **kwargs)
 
 
-def svg_response(svg_content: str, request: Request):
+def svg_response(svg_content: str, request: Request, max_age: int = 14400):
     etag = hashlib.md5(svg_content.encode("utf-8")).hexdigest()
 
     if request.headers.get("if-none-match") == etag:
@@ -55,7 +56,7 @@ def svg_response(svg_content: str, request: Request):
         content=svg_content,
         media_type="image/svg+xml",
         headers={
-            "Cache-Control": "public, max-age=14400, s-maxage=14400",
+            "Cache-Control": f"public, max-age={max_age}, s-maxage={max_age}",
             "ETag": etag,
             "Vary": "Accept-Encoding",
             # Security headers to prevent XSS
@@ -190,6 +191,22 @@ def parse_heatmap_colors(level_0, level_1, level_2, level_3, level_4):
 
     return colors if colors else None
 
+
+def fetch_github_data_or_error_svg(request: Request, username: str, token: Optional[str] = None):
+    """Fetch GitHub profile data and return an SVG fallback response on API failures."""
+    try:
+        data = github_api.get_live_github_data(username, token, raise_errors=True)
+        return data, None
+    except github_api.UserNotFoundError as exc:
+        svg_content = draw_error_card("user_not_found", username=username, message=exc.message)
+    except github_api.RateLimitExceededError as exc:
+        svg_content = draw_error_card("rate_limited", username=username, message=exc.message)
+    except github_api.GitHubApiError as exc:
+        svg_content = draw_error_card("api_error", username=username, message=exc.message)
+
+    # Keep error card cache shorter than normal cards so transient API issues recover quickly.
+    return None, svg_response(svg_content, request, max_age=300)
+
 @app.get("/api/stats")
 async def get_stats(
     request: Request,
@@ -212,8 +229,10 @@ async def get_stats(
 
     # Get optional token from Authorization header for higher rate limits
     token = get_token_from_header(request)
-    
-    data = github_api.get_live_github_data(username, token) or github_api.get_mock_data(username)
+
+    data, error_response = fetch_github_data_or_error_svg(request, username, token)
+    if error_response:
+        return error_response
 
     show_options = {
         "stars": not hide_stars,
@@ -244,7 +263,10 @@ async def get_languages(
     username = validate_username(username)
     theme = validate_theme(theme)
 
-    data = github_api.get_live_github_data(username) or github_api.get_mock_data(username)
+    token = get_token_from_header(request)
+    data, error_response = fetch_github_data_or_error_svg(request, username, token)
+    if error_response:
+        return error_response
     custom_colors = parse_custom_overrides(bg_color, title_color, text_color, border_color, font)
 
     # Parse exclude parameter into list of languages
@@ -279,7 +301,10 @@ async def get_contributions(
     start_date = validate_date(start_date)
     end_date = validate_date(end_date)
 
-    data = github_api.get_live_github_data(username) or github_api.get_mock_data(username)
+    token = get_token_from_header(request)
+    data, error_response = fetch_github_data_or_error_svg(request, username, token)
+    if error_response:
+        return error_response
     custom_colors = parse_custom_overrides(bg_color, title_color, text_color, border_color, font)
 
     # Build date_range dict if dates are provided
@@ -320,8 +345,11 @@ async def get_calendar_heatmap(
     end_date = validate_date(end_date)
 
     token = get_token_from_header(request)
-    data = github_api.get_live_github_data(username, token) or github_api.get_mock_data(username)
-    custom_colors = parse_colors(bg_color, title_color, text_color, border_color)
+    data, error_response = fetch_github_data_or_error_svg(request, username, token)
+    if error_response:
+        return error_response
+
+    custom_colors = parse_custom_overrides(bg_color, title_color, text_color, border_color)
     heatmap_colors = parse_heatmap_colors(level_0, level_1, level_2, level_3, level_4)
 
     date_range = None
@@ -384,7 +412,10 @@ async def get_trophy(
     username = validate_username(username)
     theme = validate_theme(theme)
 
-    data = github_api.get_live_github_data(username) or github_api.get_mock_data(username)
+    token = get_token_from_header(request)
+    data, error_response = fetch_github_data_or_error_svg(request, username, token)
+    if error_response:
+        return error_response
     custom_colors = parse_custom_overrides(bg_color, title_color, text_color, border_color, font)
     svg_content = trophy_card.draw_trophy_card(data, theme, custom_colors=custom_colors)
     return svg_response(svg_content, request)
@@ -405,7 +436,10 @@ async def get_streak(
     username = validate_username(username)
     theme = validate_theme(theme)
 
-    data = github_api.get_live_github_data(username) or github_api.get_mock_data(username)
+    token = get_token_from_header(request)
+    data, error_response = fetch_github_data_or_error_svg(request, username, token)
+    if error_response:
+        return error_response
     custom_colors = parse_custom_overrides(bg_color, title_color, text_color, border_color, font)
     svg_content = streak_card.draw_streak_card(data, theme, custom_colors=custom_colors)
     return svg_response(svg_content, request)
@@ -430,7 +464,10 @@ async def get_repos(
     sort_by = validate_sort_by(sort_by)
     limit = validate_limit(limit, min_val=1, max_val=10)
 
-    data = github_api.get_live_github_data(username) or github_api.get_mock_data(username)
+    token = get_token_from_header(request)
+    data, error_response = fetch_github_data_or_error_svg(request, username, token)
+    if error_response:
+        return error_response
     custom_colors = parse_custom_overrides(bg_color, title_color, text_color, border_color, font)
     svg_content = repo_card.draw_repo_card(data, theme, custom_colors=custom_colors, sort_by=sort_by, limit=limit)
     return svg_response(svg_content, request)

tests/test_api_error_fallback.py

@@ -0,0 +1,47 @@
+from fastapi.testclient import TestClient
+
+from api.main import app
+from utils import github_api
+
+
+def test_stats_returns_user_not_found_svg(monkeypatch):
+    def raise_not_found(*_args, **_kwargs):
+        raise github_api.UserNotFoundError("missing-user")
+
+    monkeypatch.setattr(github_api, "get_live_github_data", raise_not_found)
+
+    with TestClient(app) as client:
+        response = client.get("/api/stats", params={"username": "missing-user"})
+
+    assert response.status_code == 200
+    assert response.headers["content-type"].startswith("image/svg+xml")
+    assert "User Not Found" in response.text
+
+
+def test_languages_returns_rate_limited_svg(monkeypatch):
+    def raise_rate_limited(*_args, **_kwargs):
+        raise github_api.RateLimitExceededError("GitHub API rate limit exceeded")
+
+    monkeypatch.setattr(github_api, "get_live_github_data", raise_rate_limited)
+
+    with TestClient(app) as client:
+        response = client.get("/api/languages", params={"username": "octocat"})
+
+    assert response.status_code == 200
+    assert response.headers["content-type"].startswith("image/svg+xml")
+    assert "Rate Limited" in response.text
+
+
+def test_repos_returns_api_error_svg(monkeypatch):
+    def raise_api_error(*_args, **_kwargs):
+        raise github_api.GitHubApiError("Service unavailable")
+
+    monkeypatch.setattr(github_api, "get_live_github_data", raise_api_error)
+
+    with TestClient(app) as client:
+        response = client.get("/api/repos", params={"username": "octocat"})
+
+    assert response.status_code == 200
+    assert response.headers["content-type"].startswith("image/svg+xml")
+    assert "GitHub API Error" in response.text
+    assert "Service unavailable" in response.text

tests/test_error_card.py

@@ -26,4 +26,27 @@ def test_error_card_default_fallback():
     # passing unknown error_type should fall back gracefully
     result = draw_error_card("nonexistent_type", username="testuser")
     assert isinstance(result, str)
-    assert "</svg>" in result
+    assert "</svg>" in result
+
+
+def test_error_card_user_not_found_explicit():
+    result = draw_error_card("user_not_found", username="ghost")
+    assert isinstance(result, str)
+    assert "</svg>" in result
+    assert "User Not Found" in result
+    assert "ghost" in result
+
+
+def test_error_card_rate_limited_explicit():
+    result = draw_error_card("rate_limited", username="testuser")
+    assert isinstance(result, str)
+    assert "</svg>" in result
+    assert "Rate Limited" in result
+
+
+def test_error_card_api_error_explicit():
+    result = draw_error_card("api_error", username="testuser", message="Service unavailable")
+    assert isinstance(result, str)
+    assert "</svg>" in result
+    assert "GitHub API Error" in result
+    assert "Service unavailable" in result

utils/error_card.py

@@ -7,10 +7,17 @@
 def draw_error_card(error_type: str = "rate_limit", username: str = "user", message: str = "") -> str:
     WIDTH, HEIGHT = 450, 160
 
+    aliases = {
+        "invalid_user": "user_not_found",
+        "rate_limit": "rate_limited",
+        "unknown": "api_error",
+    }
+    resolved_error_type = aliases.get(error_type, error_type)
+
     config = {
-        "rate_limit": {
+        "rate_limited": {
             "icon":    "⏳",
-            "title":   "API Rate Limit Reached",
+            "title":   "Rate Limited",
             "line1":   "GitHub's API limit was hit for this session.",
             "line2":   "Add a GITHUB_TOKEN in the sidebar or .env",
             "line3":   "to increase the limit from 60 → 5,000 req/hr.",
@@ -19,22 +26,22 @@ def draw_error_card(error_type: str = "rate_limit", username: str = "user", mess
             "title_c": "#f0883e",
             "text_c":  "#c9d1d9",
         },
-        "invalid_user": {
+        "user_not_found": {
             "icon":    "❌",
-            "title":   f'User "{username}" Not Found',
+            "title":   "User Not Found",
             "line1":   "No GitHub account exists for this username.",
-            "line2":   "Double-check the spelling and try again.",
+            "line2":   f'Username: "{username}"',
             "line3":   "",
             "bg":      "#161b22",
             "border":  "#f85149",
             "title_c": "#f85149",
             "text_c":  "#c9d1d9",
         },
-        "unknown": {
+        "api_error": {
             "icon":    "⚠️",
-            "title":   "Could Not Load GitHub Data",
-            "line1":   message or "An unexpected error occurred.",
-            "line2":   "Check your internet connection and try again.",
+            "title":   "GitHub API Error",
+            "line1":   message or "Could not load GitHub profile data.",
+            "line2":   "Please try again in a few minutes.",
             "line3":   "",
             "bg":      "#161b22",
             "border":  "#e3b341",
@@ -43,7 +50,7 @@ def draw_error_card(error_type: str = "rate_limit", username: str = "user", mess
         },
     }
 
-    c = config.get(error_type, config["unknown"])
+    c = config.get(resolved_error_type, config["api_error"])
 
     dwg = svgwrite.Drawing(size=(WIDTH, HEIGHT))
     dwg.viewbox(0, 0, WIDTH, HEIGHT)