Description
Issue
The OpenNext image optimizer currently returns a 500 error when attempting to access images that are not reachable, regardless of the actual error type. For example, when an image returns a 403 Access Denied error from the source, the image optimizer returns a generic 500 Internal Server Error instead of preserving the original 403 status code.
This behavior makes debugging difficult as all image access errors appear as server errors in monitoring platforms, when in reality they are client-side issues (requesting inaccessible images).
Solution
The PR below modifies the image optimization adapter to properly handle and preserve HTTP error status codes:
When a remote image server returns a specific HTTP error code (403, 404, etc.), that same status code is preserved and returned to the client
For network errors (ENOTFOUND, ECONNREFUSED), a 404 Not Found status is returned
For other errors, appropriate status codes are determined based on error message content
Changes
Enhanced error detection in the downloadHandler function to properly handle HTTP status codes from remote servers
Improved error classification in the main handler's catch block to detect different types of errors
Added type-safe error handling with proper TypeScript guards
Improved error messages to be more descriptive
Benefits
More accurate error reporting in monitoring platforms
Easier debugging of image access issues
Better user experience with appropriate error codes
Follows HTTP standards by preserving original error status codes
Testing
Tested with images that return various HTTP status codes (403, 404) and verified that the image optimizer correctly preserves these status codes in its response.
Tested deployed to AWS and indeed passing the image optimizer an image url that returns a 403.... does result in next returning a 403
