diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0fe03ab82..fd4f63922 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -18,7 +18,10 @@ _2015-05-22_
 
 _2015-05-16_
 
- *  **New HttpUrl API.** It's like `java.net.URL` but good.
+ *  **New HttpUrl API.** It's like `java.net.URL` but good. Note that
+    `Request.Builder.url()` now throws `IllegalArgumentException` on malformed
+    URLs. (Previous releases would throw a `MalformedURLException` when calling
+    a malformed URL.)
 
  *  **We've improved connect failure recovery.** We now differentiate between
     setup, connecting, and connected and implement appropriate recovery rules
diff --git a/okhttp/src/main/java/com/squareup/okhttp/Request.java b/okhttp/src/main/java/com/squareup/okhttp/Request.java
index 9b0169dbb..2417c132a 100644
--- a/okhttp/src/main/java/com/squareup/okhttp/Request.java
+++ b/okhttp/src/main/java/com/squareup/okhttp/Request.java
@@ -143,6 +143,12 @@ public final class Request {
       return this;
     }
 
+    /**
+     * Sets the URL target of this request.
+     *
+     * @throws IllegalArgumentException if {@code url} is not a valid HTTP or HTTPS URL. Avoid this
+     *     exception by calling {@link HttpUrl#parse}; it returns null for invalid URLs.
+     */
     public Builder url(String url) {
       if (url == null) throw new IllegalArgumentException("url == null");
 
@@ -158,6 +164,12 @@ public final class Request {
       return url(parsed);
     }
 
+    /**
+     * Sets the URL target of this request.
+     *
+     * @throws IllegalArgumentException if the scheme of {@code url} is not {@code http} or {@code
+     *     https}.
+     */
     public Builder url(URL url) {
       if (url == null) throw new IllegalArgumentException("url == null");
       HttpUrl parsed = HttpUrl.get(url);