When implementing network requests on mobile devices a lot of things can go wrong: no network connection or the server responds with an error. In either case you need to make sure you deal with the error and, if necessary, inform the user about the issue. In the tutorial on simple error handling we introduced the basics of dealing with those errors in Retrofit.
In this short tutorial, we'll apply the same approach for synchronous requests. This is helpful when you're doing synchronous requests, for example on background services.
Retrofit Series Overview
- Getting Started and Creating an Android Client
- Basics of API Description
- Creating a Sustainable Android Client
- URL Handling, Resolution and Parsing
- How to Change API Base Url at Runtime
- Multiple Server Environments (Develop, Staging, Production)
- Share OkHttp Client and Converters between Retrofit Instances
- Upgrade Guide from 1.9
- Beyond Android: Retrofit for Java Projects
- How to use OkHttp 3 with Retrofit 1
- Synchronous and Asynchronous Requests
- Send Objects in Request Body
- Add Custom Request Header
- Manage Request Headers in OkHttp Interceptor
- Dynamic Request Headers with @HeaderMap
- Multiple Query Parameters of Same Name
- Optional Query Parameters
- Send Data Form-Urlencoded
- Send Data Form-Urlencoded Using FieldMap
- How to Add Query Parameters to Every Request
- Add Multiple Query Parameter With QueryMap
- How to Use Dynamic Urls for Requests
- Constant, Default and Logic Values for POST and PUT Requests
- Cancel Requests
- Reuse and Analyze Requests
- Optional Path Parameters
- How to Send Plain Text Request Body
- Customize Network Timeouts
- How to Trust Unsafe SSL certificates (Self-signed, Expired)
- Dynamic Endpoint-Dependent Interceptor Actions
- How to Update Objects on the Server (PUT vs. PATCH)
- How to Delete Objects on the Server
- Introduction to (Multiple) Converters
- Adding & Customizing the Gson Converter
- Implementing Custom Converters
- How to Integrate XML Converter
- Access Mapped Objects and Raw Response Payload
- Supporting JSON and XML Responses Concurrently
- Handling of Empty Server Responses with Custom Converter
- Send JSON Requests and Receive XML Responses (or vice versa)
- Unwrapping Envelope Responses with Custom Converter
- Wrapping Requests in Envelope with Custom Converter
- Define a Custom Response Converter
- Simple Error Handling
- Error Handling for Synchronous Requests
- Catch Server Errors Globally with Response Interceptor
- How to Detect Network and Conversion Errors in onFailure
Possible Retrofit Errors
Retrofit's default response handling separates the results into three categories:
- Request failed (e.g., no network connection)
- Request succeeded, but server responded with error (status code 4xx or 5xx)
- Request succeeded, and server responded with success (status code 2xx)
Reminder: Asynchronous Environment
In the asynchronous environment you'll get a separate callback onFailure() for the first result case (Request failed). The second and third result case is combined in one asynchronous callback onResponse(). You can differentiate between these two cases by checking with response.isSuccessful(). If the request failed, we introduced an error parser to get a useful error object.
Synchronous Environment
The general approach when doing synchronous requests is very similar. Let's look at the general way to make synchronous requests:
GitHubService githubService = ... // create in your app
Call<List<GitHubRepo>> call = githubService.reposForUser("fs-opensource");
Response<List<GitHubRepo>> response = call.execute();
At this point, you won't be able to deal with any errors. Let's catch the case where the request itself fails by wrapping it into a try-catch clause:
try {
Response<List<GitHubRepo>> response = call.execute();
} catch (IOException e) {
Toast.makeText(ErrorHandlingActivity.this, "network failure :(", Toast.LENGTH_SHORT).show();
}
When Retrofit throws an IOException, you know that the request failed. Deal with that according to your app requirements.
The next step would be to catch the problem when the server responds with an error. The approach is identical to the asynchronous environment:
Response<List<GitHubRepo>> response = call.execute();
if (response.isSuccessful()) {
Toast.makeText(ErrorHandlingActivity.this, "server returned so many repositories: " + response.body().size(), Toast.LENGTH_SHORT).show();
// todo display the data instead of just a toast
}
else {
ApiError apiError = ErrorUtils.parseError(response);
Toast.makeText(ErrorHandlingActivity.this, apiError.getMessage(), Toast.LENGTH_SHORT).show();
}
When the response comes with data, we'll display it in the app. If the response is an error response, we use the ErrorUtils to parse it into a useful error object.
Lastly, let's combine everything together:
try {
Response<List<GitHubRepo>> response = call.execute();
if (response.isSuccessful()) {
Toast.makeText(ErrorHandlingActivity.this, "server returned so many repositories: " + response.body().size(), Toast.LENGTH_SHORT).show();
// todo display the data instead of just a toast
}
else {
ApiError apiError = ErrorUtils.parseError(response);
Toast.makeText(ErrorHandlingActivity.this, apiError.getMessage(), Toast.LENGTH_SHORT).show();
}
} catch (IOException e) {
Toast.makeText(ErrorHandlingActivity.this, "network failure :( inform the user and possibly retry", Toast.LENGTH_SHORT).show();
}
Outlook
In this tutorial you've learned how you can apply the general error handling approach to synchronous requests. Make sure to deal with the potential problems to make your app even better!
If you've feedback or a question, let us know in the comments or on twitter @futurestud_io.
Enjoy coding & make it rock!
