"success": false, "error": "code": "PDF_GEN_FAILED", "message": "Could not render chart data: time series missing.", "recoverable": true, "suggestedAction": "retry", "userDataPreserved": true
try: pdf = generate_pdf(data) return pdf except Exception as e: logger.error(f"PDF generation failed: str(e)") return jsonify( "success": False, "error": "code": "PDF_RENDER_ERROR", "message": "Report could not be assembled due to invalid data.", "recoverable": False, "userDataPreserved": True ), 200 # still 200 to avoid download interrupt If PDF fails, offer structured data export.
If the PDF library fails mid‑generation, catch and transform the error. gracefully broken pdf download
Return a clean error message before ever calling the PDF engine. Never send an error inside a PDF binary. Use structured responses. Success (200 OK with PDF) Content-Type: application/pdf Content-Disposition: attachment; filename="report.pdf" Failure (200 OK with JSON) Even for errors, use 200 OK to avoid browser download interruption, then handle on frontend.
Send anonymized failure reports to your analytics. Never send an error inside a PDF binary
async function downloadPDF() const response = await fetch('/api/generate-pdf', method: 'POST', body: formData ); const contentType = response.headers.get('content-type'); if (contentType.includes('application/json')) const error = await response.json(); showGracefulFailureDialog(error); return;
Content-Type: application/json
# DON'T DO THIS output = BytesIO() pdf = canvas.Canvas(output) pdf.drawString(100, 750, "Report") # crash here – user gets zero-byte or partial PDF
// Normal PDF download const blob = await response.blob(); const url = URL.createObjectURL(blob); const a = document.createElement('a'); a.href = url; a.download = 'report.pdf'; a.click(); URL.revokeObjectURL(url); Send anonymized failure reports to your analytics
function showGracefulFailureDialog(error) const dialog = <div class="pdf-error-card"> <h3>⚠️ PDF could not be generated</h3> <p>$error.message</p> $error.recoverable ? '<button onclick="retryPDF()">Try again</button>' : '' <button onclick="exportRawData()">Download data as CSV/JSON</button> <button onclick="contactSupport()">Report issue</button> <details> <summary>Technical details</summary> <pre>$error.code</pre> </details> </div> ; showModal(dialog);
Some browsers treat 4xx/5xx responses as download failures and show generic "Failed – Network error". Step 3: Graceful Failure Response on Frontend When receiving a JSON error instead of a PDF blob, show a user‑friendly overlay.
