api-download-401-pdf-body

What problem does it solve?

This skill resolves the issue where file downloads implemented with fetch and blob return incorrect content (such as HTML error pages or corrupt files) instead of the expected PDF or document, which occurs when backend authentication middleware returns a 401 status but still includes the fetched file body in the response.

Core Features & Use Cases

• Targeted Debugging Workflow: Provides step-by-step curl commands to test download endpoints with no auth, invalid tokens, and empty bearer tokens to isolate the root cause of mismatched status codes and response bodies.
• Root Cause Identification: Explains the common backend route ordering bug where auth checks run after S3 (or similar object storage) file fetches, leading to 401 responses carrying file binary data.
• Multiple Fix Options: Offers 4 distinct solutions ranging from removing unnecessary auth on non-sensitive download endpoints, reordering middleware to run auth checks before file fetches, adding frontend response validation, to modifying backend error handling to exclude file bodies from 401 responses.
• Real-World Example: Includes a documented case from UMAC AI where invalid auth tokens caused students to receive corrupt PDFs instead of the correct lesson attachments.

Quick Start

Use this skill to diagnose and fix your file download endpoint that returns incorrect content when authentication fails, following the provided testing steps and fix recommendations.