Don’t force people to understand how the Internet works
Transforming default error messages to reduce support time and build a better experience
At Clef, we actively maintain two mobile apps: Clef for iOS and Clef for Android, both of which are used by hundreds of thousands of people to log in. Because many of them are non-technical, we work hard to provide error messages that are easy to understand and take action on.
Consistent support requests for one type of error
A couple of months ago, while looking through our support inbox, we noticed a disturbing trend: over the past year, the term “request timed out” had appeared in support messages more than 100 times. While that was only a small percentage of total requests, each time the issue was triaged, the customer was told the same thing: check your Internet connection to make sure it was active and toggle Airplane mode or their WiFi if you are still having issues.
Digging deeper, we found that “request timed out” wasn’t the only error that consistently appeared (and was responded to with the “toggle your Internet” response). There were a handful of common errors that were all met with the same “toggle your Airplane more or WiFi” solution.
These errors weren’t being returned by our API or created in the app, rather they were coming directly from the NSURLErrorDomain, the kind of error returned when network requests fail.
To a developer, a support person, or the iOS SDK team, there errors are very understandable: they describe different reasons why the request to a URL might fail. For everyone else, however, our support load indicated that the errors were completely unintelligible: people didn’t understand what “timed out” meant or why a “hostname might not be verified”. All they saw was a cryptic message and no solution to move forward.
Translating cryptic error messages
To fix this problem, we started using the RMErrors library created by Ride. It lets us easily map network errors (and ranges of errors) to customized error messages. This let us provide the same support we’d been providing through email, in the app.
Most people aren’t developers
As a developer, it’s easy to forget that most of the people who use the software we build are non-technical. They don’t care why the app isn’t working, they just want to fix the issue.
We just released these new error messages in v3.5.6 of Clef for iOS and we’re going to be making the same changes in our Android app. Though it’s too early to tell whether we’ve completely solved the issue, we’re excited to help people help themselves.
If your app uses the Internet, and you’re not already transforming network connectivity error messages into useful directions for your customers, you should.
Two Factor Authenticity is a community publication on Medium, curated by Clef. For more from the Clef team, follow us on twitter @getclef
