How to Stop Blank JSON Pages on Failed Downloads: Two Effective Strategies

Background

When a file download fails and the browser displays a blank page containing raw JSON, the user experience is severely degraded. The root cause is usually that the server returns an error payload instead of a proper file stream, and the client does not handle the error gracefully.

Two Architectural Options

Pre‑check API : The front‑end first calls a lightweight endpoint that validates whether the download can proceed (e.g., permission check, file existence, quota). If the check succeeds, the client initiates a separate request to the file‑download endpoint.

Pre‑check API that returns a download URL : The validation endpoint, after confirming the conditions, generates a signed, time‑limited URL (or a direct path) and returns it to the client. The client then performs a single request to that URL to obtain the file.

Detailed Analysis

Pre‑check API

Latency perception : An extra round‑trip adds a few hundred milliseconds, which may be noticeable on high‑latency networks.

API dependency : The download flow now depends on the availability and performance of the validation service.

Reduced invalid traffic : By rejecting unauthorized or malformed requests early, the server saves bandwidth and CPU cycles.

UX feedback : The client can display a clear message (e.g., “Insufficient permissions”) before attempting the download.

Pre‑check API Returning a Download URL

Security considerations : The URL must be signed (e.g., HMAC, JWT) and include an expiration timestamp to prevent reuse by unauthorized parties.

Link expiration : Typical expiration windows range from 5 minutes to 1 hour, balancing usability and security.

Smoother UX : The user clicks once and the browser starts the download immediately, eliminating the perceived delay.

Server load : Because the actual file is served directly by a static file server or CDN, the application server only handles the validation step.

Best‑Practice Guidelines

Prioritize user experience : Provide immediate, understandable feedback and minimize the number of clicks required to start a download.

Enforce security : Use signed URLs, enforce authentication, and set short expiration times to mitigate leakage.

Optimize resource usage : Offload large file delivery to a CDN or object storage (e.g., S3, Azure Blob) and keep the application server focused on business logic.

Recommended Implementation

The second pattern—validation endpoint returns a signed, time‑limited download URL—is generally preferred because it combines clear UX with efficient server utilization.

Implementation Steps

Expose a /api/download/validate endpoint that checks user permissions, file existence, and any business rules.

If validation succeeds, generate a signed URL. Example (Node.js with AWS SDK):

const params = {Bucket: 'my-bucket', Key: fileKey, Expires: 300}; // 5 minutes
const url = s3.getSignedUrl('getObject', params);
res.json({downloadUrl: url});

Return the URL in a JSON payload: {"downloadUrl": "https://..."} On the client side, fetch the validation endpoint, then set window.location.href = response.downloadUrl or create an invisible <a> element with download attribute to trigger the download.

Configure the storage service or CDN to serve the file with appropriate Content‑Disposition: attachment headers so the browser treats it as a download.

Security Hardening Measures

Set a short expiration (e.g., 5–15 minutes) on the signed URL.

Generate a unique URL per request; do not reuse static URLs.

Require the user to be authenticated (e.g., JWT, session cookie) before the validation endpoint is called.

Log URL generation and download attempts for audit purposes.

Scalability Considerations

Use a CDN or object‑storage service to serve the actual file, reducing load on the application server.

Implement rate‑limiting on the validation endpoint to protect against abuse.

Cache validation results for a short period (e.g., 30 seconds) when the same user repeatedly requests the same file.

Practical Example

Large‑scale file‑sharing services such as Dropbox or Baidu Cloud generate per‑request signed URLs that expire after a few minutes. This approach delivers a seamless download experience while ensuring that only authorized users can access the file.