diff --git a/pkgs/http/lib/src/base_response.dart b/pkgs/http/lib/src/base_response.dart
index ed95f6cdb2..24c7dd3f34 100644
--- a/pkgs/http/lib/src/base_response.dart
+++ b/pkgs/http/lib/src/base_response.dart
@@ -46,6 +46,11 @@ abstract class BaseResponse {
   /// If a header value contains whitespace then that whitespace may be replaced
   /// by a single space. Leading and trailing whitespace in header values are
   /// always removed.
+  ///
+  /// Some headers may be excluded by the client for security or privacy
+  /// reasons. For example, browser-based clients can only return headers in the
+  /// CORS safelist or specifically allowed by the server.
+  ///
   // TODO(nweiz): make this a HttpHeaders object.
   final Map<String, String> headers;