From a395cadd87a3789c7ce9397022535b484fd4d9d0 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Jonas=20Uek=C3=B6tter?= <ueman@users.noreply.github.com>
Date: Mon, 16 Oct 2023 19:26:15 +0200
Subject: [PATCH] Improve exception message for DioException.badResponse
 (#1998)

Since we receive a lot of issues around the topic of status code, I
think we should improve message of it. So I've made it more descriptinve
and actionable.

### New Pull Request Checklist

- [x] I have read the
[Documentation](https://pub.dev/documentation/dio/latest/)
- [x] I have searched for a similar pull request in the
[project](https://github.com/cfug/dio/pulls) and found none
- [x] I have updated this branch with the latest `main` branch to avoid
conflicts (via merge from master or rebase)
- [x] I have added the required tests to prove the fix/feature I'm
adding
- [x] I have updated the documentation (if necessary)
- [x] I have run the tests without failures
- [x] I have updated the `CHANGELOG.md` in the corresponding package

### Additional context and info (if any)

<!-- Provide more context and info about the PR. -->
---
 dio/CHANGELOG.md               |  1 +
 dio/lib/src/dio_exception.dart | 37 ++++++++++++++++++++++++++++++++--
 2 files changed, 36 insertions(+), 2 deletions(-)

diff --git a/dio/CHANGELOG.md b/dio/CHANGELOG.md
index 0c275cbd5..0e30b887f 100644
--- a/dio/CHANGELOG.md
+++ b/dio/CHANGELOG.md
@@ -6,6 +6,7 @@ See the [Migration Guide][] for the complete breaking changes list.**
 ## Unreleased
 
 - Raise warning for `Map`s other than `Map<String, dynamic>` when encoding request data.
+- Improve exception messages
 
 ## 5.3.3
 
diff --git a/dio/lib/src/dio_exception.dart b/dio/lib/src/dio_exception.dart
index a19544bc1..a9a54f85d 100644
--- a/dio/lib/src/dio_exception.dart
+++ b/dio/lib/src/dio_exception.dart
@@ -86,8 +86,7 @@ class DioException implements Exception {
   }) =>
       DioException(
         type: DioExceptionType.badResponse,
-        message: 'The request returned an '
-            'invalid status code of $statusCode.',
+        message: _badResponseExceptionMessage(statusCode),
         requestOptions: requestOptions,
         response: response,
         error: null,
@@ -211,4 +210,38 @@ class DioException implements Exception {
     }
     return msg;
   }
+
+  /// Because of [ValidateStatus] we need to consider all status codes when
+  /// creating a [DioException.badResponse].
+  static String _badResponseExceptionMessage(int statusCode) {
+    var message = '';
+    if (statusCode >= 100 && statusCode < 200) {
+      message =
+          'This is an informational response - the request was received, continuing processing';
+    } else if (statusCode >= 200 && statusCode < 300) {
+      message =
+          'The request was successfully received, understood, and accepted';
+    } else if (statusCode >= 300 && statusCode < 400) {
+      message =
+          'Redirection: further action needs to be taken in order to complete the request';
+    } else if (statusCode >= 400 && statusCode < 500) {
+      message =
+          'Client error - the request contains bad syntax or cannot be fulfilled';
+    } else if (statusCode >= 500 && statusCode < 600) {
+      message =
+          'Server error - the server failed to fulfil an apparently valid request';
+    } else {
+      message =
+          'A response with a status code that is not within the range of inclusive 100 to exclusive 600'
+          'is a non-standard response, possibly due to the server\'s software.';
+    }
+
+    return ''
+        'This exception was thrown because the response has a status code of $statusCode '
+        'and RequestOptions.validateStatus was configured to throw for this status code.\n'
+        'The status code of $statusCode has the following meaning: "$message"\n.'
+        'Read more about status codes at https://developer.mozilla.org/en-US/docs/Web/HTTP/Status\n'
+        'In order to resolve this exception you typically have either to verify '
+        'and fix your request code or you have to fix the server code.';
+  }
 }