12.8 · Building URLs, reading headers, classifying errors and timeouts

Most networking bugs are not in the transport; they are in how a URL was built, how a header was read, and how an error was interpreted. These questions are the details that cause incidents.

Mental model. A request has three layers of failure: the URL you built, the transport (URLError), and the server’s answer (a status code). Treat them separately.

URLs and headers

Query encoding, percent-encoding sets, and case-insensitive header access.

  1. What goes wrong when you build a URL with string concatenation, and how do URLComponents, percent-encoding sets and the plus sign behave? 12.8.1 · L2
    Never build a query by concatenating strings. URLComponents with URLQueryItem encodes each name and value for you, but know what it does not do. In the check…
  2. Are HTTP header names case-sensitive in URLSession, and how do you read them safely? 12.8.2 · L2
    HTTP header names are case-insensitive by the protocol (and HTTP/2 and HTTP/3 send them in lowercase), so a server may answer with ETag, Etag or etag. In…

Errors and timeouts

Which failures are URLError, which are status codes, and what each timeout measures.

  1. How do you classify what URLSession reports: which failures are URLError, which are not, and which are worth retrying? 12.8.3 · L3
    A transport failure is thrown as a URLError with a code; an HTTP error status is not an error at all from URLSession’s point of view (a 503 comes back as a…
  2. What do timeoutIntervalForRequest, timeoutIntervalForResource and the per-request timeout measure, and how do they interact? 12.8.4 · L3
    There are three numbers and they measure different things. timeoutIntervalForRequest (default 60 s) is an idle timeout: how long the connection may go without…

More in Networking