introduced the ClientMessage class so client errors can include title, message, and button text.

modules/core/src/retrofit/core/Callback.java

@@ -35,7 +35,7 @@ public interface Callback<T> {
    *
    * @param message to show user, or null if no message was returned
    */
-  void clientError(String message);
+  void clientError(ClientMessage message);
 
   /**
    * We reached the server, but it encountered an error. Please try again

modules/core/src/retrofit/core/ClientMessage.java

+// Copyright 2010 Square, Inc.
+package retrofit.core;
+
+/**
+ * Information for a client error screen or dialog, including the screen title,
+ * message, and button label. Any field may be null.
+ *
+ * @author Eric Burke (eric@squareup.com)
+ */
+public class ClientMessage {
+  private final String title;
+  private final String message;
+  private final String buttonLabel;
+
+  /**
+   * Constructs a new message, any argument may be null.
+   *
+   * @param title       a few words for a dialog title or heading, or null.
+   * @param message     a sentence or two with a more detailed, user friendly
+   *                    message, or null.
+   * @param buttonLabel text to display on a button, or null.
+   */
+  public ClientMessage(String title, String message, String buttonLabel) {
+    this.title = title;
+    this.message = message;
+    this.buttonLabel = buttonLabel;
+  }
+
+  /** Returns a few words useful for a dialog title or heading, might be null. */
+  public String getTitle() {
+    return title;
+  }
+
+  /** Returns a sentence or two with a user friendly message. */
+  public String getMessage() {
+    return message;
+  }
+
+  /** Returns text for a button, or null. */
+  public String getButtonLabel() {
+    return buttonLabel;
+  }
+}

modules/http/src/retrofit/http/CallbackResponseHandler.java

@@ -7,6 +7,7 @@ import org.apache.http.HttpResponse;
 import org.apache.http.StatusLine;
 import org.apache.http.client.ResponseHandler;
 import retrofit.core.Callback;
+import retrofit.core.ClientMessage;
 
 import java.io.IOException;
 import java.util.logging.Level;
@@ -114,7 +115,7 @@ public abstract class CallbackResponseHandler<T>
       String body = new String(HttpClients.entityToBytes(entity), "UTF-8");
       logger.fine("Server returned " + statusCode + ", "
           + statusLine.getReasonPhrase() + ". Body: " + body);
-      callback.clientError(parseServerMessage(statusCode, body));
+      callback.clientError(parseClientMessage(body));
     } else {
       logger.fine("Server returned " + statusCode + ", "
           + statusLine.getReasonPhrase() + ".");
@@ -123,6 +124,29 @@ public abstract class CallbackResponseHandler<T>
     return null;
   }
 
+  /**
+   * Parses a client error message, assuming the JSON looks like this:
+   * <pre>
+   * {
+   *   "message_title": "Email Address Taken",
+   *   "message": "That email is already taken. Please enter another address.",
+   *   "button_label": "Change"
+   * }</pre>
+   */
+  private static ClientMessage parseClientMessage(String body) {
+    try {
+      ClientError error = new Gson().fromJson(body, ClientError.class);
+      if (error != null) {
+        return new ClientMessage(
+            error.message_title, error.message, error.button_label);
+      }
+    } catch (Throwable t) {
+      // The server error takes precedence.
+      logger.log(Level.WARNING, t.getMessage(), t);
+    }
+    return null;
+  }
+
   /**
    * Parses a server error message.
    */
@@ -146,4 +170,13 @@ public abstract class CallbackResponseHandler<T>
   static class ServerError {
     String message;
   }
+
+  /**
+   * Gson POJO for parsing client error messages.
+   */
+  static class ClientError {
+    String message;
+    String message_title;
+    String button_label;
+  }
 }

modules/http/src/retrofit/http/UiCallback.java

@@ -2,6 +2,7 @@
 package retrofit.http;
 
 import retrofit.core.Callback;
+import retrofit.core.ClientMessage;
 import retrofit.core.MainThread;
 
 /**
@@ -48,7 +49,7 @@ public final class UiCallback<T> implements Callback<T> {
     });
   }
 
-  public void clientError(final String message) {
+  public void clientError(final ClientMessage message) {
     mainThread.execute(new Runnable() {
       public void run() {
         delegate.clientError(message);