feat: add custom exception unwrapping in interceptors

[meylis1998]

Summary

• Adds mechanism to throw custom exceptions directly from interceptors instead of wrapping them in DioException
• Implements solution for issue Developer should throw custom exception in interceptor #1950

Changes

• Add throwInnerErrorOnFinish flag to DioException (default false)
• Add DioException.customError() factory constructor for convenient creation
• Add rejectCustomError() method to RequestInterceptorHandler, ResponseInterceptorHandler, and ErrorInterceptorHandler
• Unwrap marked exceptions in fetch() final catch block

Example Usage

// In interceptor
dio.interceptors.add(InterceptorsWrapper(
  onResponse: (response, handler) {
    if (response.statusCode == 401) {
      handler.rejectCustomError(
        UnauthorizedException('Token expired'),
        response.requestOptions,
      );
      return;
    }
    handler.next(response);
  },
));

// Caller can now catch custom exception directly:
try {
  await dio.get('/api');
} on UnauthorizedException catch (e) {
  // Now works!
}

Test plan

• Added tests for rejectCustomError() from all three handler types
• Added test verifying regular reject() still wraps in DioException
• Added tests for DioException.customError() factory
• Added tests for copyWith() preserving the flag
• Added test for callFollowingErrorInterceptor parameter
• Added test for QueuedInterceptor support
• All existing tests pass

Closes #1950

[Copilot]

Pull request overview

This PR adds first-class support for propagating custom exceptions thrown from interceptors to callers (instead of always wrapping them in DioException), addressing issue #1950.

Changes:

• Introduces throwInnerErrorOnFinish on DioException plus a DioException.customError() factory to mark exceptions intended for unwrapping.
• Adds rejectCustomError() helper APIs to interceptor handlers to create/propagate marked errors consistently.
• Updates DioMixin.fetch() to unwrap and throw the inner error at the final normalization catch; adds interceptor-level tests validating behavior.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
dio/lib/src/dio_exception.dart	Adds unwrapping flag + customError() factory and preserves flag via copyWith().
dio/lib/src/interceptor.dart	Adds rejectCustomError() to request/response/error interceptor handlers.
dio/lib/src/dio_mixin.dart	Unwraps marked DioExceptions in the final fetch() catch block.
dio/test/interceptor_test.dart	Adds tests for unwrapping behavior, factory, copyWith(), callFollowingErrorInterceptor, and queued interceptors.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Unwrapping via throw dioException.error!; replaces the original stack trace with the stack trace from this catch block. That makes custom exceptions harder to debug since dioException.stackTrace (captured earlier) is lost. Consider throwing the inner error with the original stack trace (e.g., Error.throwWithStackTrace(dioException.error!, dioException.stackTrace)).

Suggested change

	// instead of the DioException wrapper.
	if (dioException.throwInnerErrorOnFinish && dioException.error != null) {
	throw dioException.error!;
	// instead of the DioException wrapper, preserving its original
	// stack trace when available.
	if (dioException.throwInnerErrorOnFinish && dioException.error != null) {
	Error.throwWithStackTrace(
	dioException.error!,
	dioException.stackTrace ?? StackTrace.current,
	);