What's the difference between `WKNavigationDelegate` `didFail` and `didFailProvisionalNavigation`

Question

iOS WKWebView's WKNavigationDelegate has two methods to handle a failed navigation:

• webView(_:didFail:withError:): "Tells the delegate that an error occurred during navigation."

• webView(_:didFailProvisionalNavigation:withError:): "Tells the delegate that an error occurred during the early navigation process."

The docs only tell us that the one type occurs earlier in the navigation process than the other. The error arguments are generic, so no help there. Brave and Firefox iOS only handle didFailProvisionalNavigation as far as I can tell from reading their source.

My questions are:

1. What's the difference exactly between the two types of errors?
2. Is there a list of errors that can occur for each?
3. When is it necessary to handle didFail seeing that browsers don't seem to handle that?

Answer 1

webView(_:didFailProvisionalNavigation:withError:)

This method handles errors that happen before the resource of the url can even be reached. These errors are mostly related to connectivity, the formatting of the url, or if using urls which are not supported.

The error codes delivered here are found in https://developer.apple.com/documentation/cfnetwork/cfnetworkerrors

Typical examples are

kCFURLErrorTimedOut = -1001 // timed out
kCFURLErrorUnsupportedURL = -1002 // unsupported URL
kCFURLErrorCannotFindHost = -1003 // host can not be found
kCFURLErrorFileDoesNotExist = -1100 // file does not exist on the server

webView(_:didFail:withError:)

Here, errors are reported that happen while loading the resource. These are usually errors caused by the content of the page, like invalid code in the page itself that the parser can't handle.