What is the *url.Error that http.Client.Do returns, and how do you reach its cause?

## The wrapper you always get Every failure returned by `http.Client.Do`, `http.Get` and friends is a `*url.Error` from `net/url`. It is a plain struct: ```go type Error struct { Op string URL string Err error } ``` - **`Op`** is the operation. For the HTTP client it is the request method with only the first letter capitalised - `"Get"`, `"Post"`, `"Head"`. - **`URL`** is the URL that was being requested. - **`Err`** is the real cause: a `*net.OpError` for a refused dial, a `*net.DNSError` for a name that would not resolve, a TLS error, `io.EOF` for a connection that closed under you, `context.Canceled` or `context.DeadlineExceeded` for a cancelled or expired request context, or the client's own timeout error. Its `Error()` method is defined as the operation, the quoted URL, then the cause, which is why the text always has that recognisable shape: ``` Get "https://api.example.com/v1/orders": dial tcp 10.0.0.7:443: connect: connection refused ``` ## Getting at it correctly ```go var urlErr *url.Error if errors.As(err, &urlErr) { // urlErr.Op, urlErr.URL, urlErr.Err } ``` A direct type assertion, `urlErr, ok := err.(*url.Error)`, happens to work when you call the client yourself, and it is still the wrong reflex. As soon as one layer between the call and the check adds context, the assertion fails while `errors.As` keeps walking the chain. The same reasoning kills the other tempting shortcut, matching substrings of `err.Error()`: that text embeds a resolved IP address, a port, and a platform-specific syscall message, none of which are part of any contract. ## What you can ask it `*url.Error` has three methods worth knowing: - **`Unwrap() error`** returns `Err`, which is what makes `errors.Is` and `errors.As` see straight through the wrapper. `errors.Is(err, io.EOF)` and `errors.Is(err, context.Canceled)` both work directly on what `Do` returned. - **`Timeout() bool`** reports whether the cause itself claims to be a timeout - it delegates to the wrapped error's own `Timeout` method if it has one. Because of this method, `*url.Error` satisfies the `net.Error` interface, so `var netErr net.Error; errors.As(err, &netErr)` is the transport-agnostic form of the same question. - **`Temporary() bool`** exists and is deprecated. It was never well defined, different types set it inconsistently, and it never answered the question people wanted, which is whether a retry is safe. Do not branch on it. ## Attributing a timeout `Timeout()` tells you a deadline fired, not *which* one. To attribute it, test the cause. If you attached a context with a deadline via `http.NewRequestWithContext`, then `errors.Is(err, context.DeadlineExceeded)` is true when that deadline is what ended the request, and `errors.Is(err, context.Canceled)` is true when something cancelled it explicitly - a parent giving up, a sibling task failing. An expiry of the client's own overall timeout also reports `Timeout() true`. The portable habit is therefore: use `Timeout()` for the boolean *was this a timeout*, and the `context` sentinels for *was it my deadline or my cancellation*, rather than assuming a particular sentinel sits underneath the client's own timeout. ## Why this matters beyond neatness A nightly reconciliation job that calls a partner API will meet all of these within a month: refused dials during the partner's deploy, DNS blips, expired certificates, deadlines it set itself, and connections that die mid-flight. If the job's only handling is `if err != nil { log(err); return err }`, then every one of them is the same event, and the person writing the postmortem has a pile of one-line strings and no way to count them by kind. Classifying with `errors.As` at the call site - while the error still has a type - is what turns that pile into a table. ## The shape to remember One sentence: the client wraps, `errors.As` unwraps, the type answers the question, and the text is for humans only.