From 00c3363ed712047b7341051cecfe211fb6f51254 Mon Sep 17 00:00:00 2001 From: elliotechne Date: Sun, 29 Mar 2026 15:49:51 -0400 Subject: [PATCH] feat: serve lightweight HTML page on 503 errors When the service is under memory pressure and returns 503s, browser clients now receive a minimal static HTML fallback page (no JS, no external resources) instead of a raw JSON error. API clients continue to receive JSON responses. Handles the health-check and Stripe 503 paths via the new global errorhandler. Co-Authored-By: Claude Sonnet 4.6 --- app/middleware/error_handler.py | 18 +++++++++- templates/503.html | 63 +++++++++++++++++++++++++++++++++ 2 files changed, 80 insertions(+), 1 deletion(-) create mode 100644 templates/503.html diff --git a/app/middleware/error_handler.py b/app/middleware/error_handler.py index 9c4192e..a75ec9d 100644 --- a/app/middleware/error_handler.py +++ b/app/middleware/error_handler.py @@ -2,13 +2,19 @@ Global Error Handlers """ -from flask import jsonify +from flask import jsonify, render_template, request from werkzeug.exceptions import HTTPException from app.utils.logger import setup_logger logger = setup_logger(__name__) +def _wants_html(): + """Return True if the client prefers an HTML response (i.e. browser request).""" + best = request.accept_mimetypes.best_match(['text/html', 'application/json']) + return best == 'text/html' + + def register_error_handlers(app): """Register global error handlers for the Flask app""" @@ -62,6 +68,16 @@ def internal_server_error(error): 'message': 'An unexpected error occurred' }), 500 + @app.errorhandler(503) + def service_unavailable(error): + """Serve a lightweight page for browser clients when the service is overloaded.""" + if _wants_html(): + return render_template('503.html'), 503 + return jsonify({ + 'error': 'Service unavailable', + 'message': 'The service is temporarily unavailable. Please try again later.' + }), 503 + @app.errorhandler(HTTPException) def handle_http_exception(error): """Handle all HTTP exceptions""" diff --git a/templates/503.html b/templates/503.html new file mode 100644 index 0000000..7371a0e --- /dev/null +++ b/templates/503.html @@ -0,0 +1,63 @@ + + + + + +Service Temporarily Unavailable - TF Visualizer + + + +
+
503
+

Service Temporarily Unavailable

+

We're experiencing high load or performing maintenance.
Please try again in a moment.

+ Try Again +
+ +