RequestError

public struct RequestError : Error
extension RequestError: TypedContentAccessors

Information about a failed resource request.

Siesta can encounter errors from many possible sources, including:

  • client-side encoding / request creation issues,
  • network connectivity problems,
  • protocol issues (e.g. certificate problems),
  • server errors (404, 500, etc.), and
  • client-side parsing and entity validation failures.

RequestError presents all these errors in a uniform structure. Several properties preserve diagnostic information, which you can use to intercept specific known errors, but these diagnostic properties are all optional. They are not even mutually exclusive: Siesta errors do not break cleanly into HTTP-based vs. Error / NSError-based, for example, because network implementations may sometimes provide both an underlying Error and an HTTP diagnostic.

The one ironclad guarantee that RequestError makes is the presence of a userMessage.

  • A description of this error suitable for showing to the user. Typically messages are brief and in plain language, e.g. “Not found,” “Invalid username or password,” or “The internet connection is offline.”

    Note

    This property is similar to Swift’s Error.localizedDescription, but is not optional. Siesta guarantees the presence of a user-displayable message on a RequestError, so you never have to come up with a default error message for your UI.

    Declaration

    Swift

    public var userMessage: String
    Show on GitHub

  • The HTTP status code (e.g. 404) if this error came from an HTTP response.

    Declaration

    Swift

    public var httpStatusCode: Int?
    Show on GitHub

  • The response body if this error came from an HTTP response. Its meaning is API-specific.

    Declaration

    Swift

    public var entity: Entity<Any>?
    Show on GitHub

  • Details about the underlying error. Errors originating from Siesta will have a cause from RequestError.Cause. Errors originating from the NetworkingProvider or custom ResponseTransformers have domain-specific causes.

    Declaration

    Swift

    public var cause: Error?
    Show on GitHub

  • The time at which the error occurred.

    Declaration

    Swift

    public let timestamp: TimeInterval
    Show on GitHub

  • Initializes the error using a network response.

    If the userMessage parameter is nil, this initializer uses error or the response’s status code to generate a user message. That failing, it gives a generic failure message.

    Declaration

    Swift

    public init(
        response: HTTPURLResponse?,
        content: Any?,
        cause: Error?,
        userMessage: String? = nil)
    Show on GitHub

  • Initializes the error using an underlying error.

    Declaration

    Swift

    public init(
        userMessage: String,
        cause: Error,
        entity: Entity<Any>? = nil)
    Show on GitHub

  • Typed content accessors such as .text and .jsonDict apply to entity?.content.

    Declaration

    Swift

    public var entityForTypedContentAccessors: Entity<Any>? { get }
    Show on GitHub

  • Underlying causes of errors reported by Siesta. You will find these on the RequestError.cause property. (Note that cause may also contain errors from the underlying network library that do not appear here.)

    The primary purpose of these error causes is to aid debugging. Client code rarely needs to work with them, but they can be useful if you want to add special handling for specific errors.

    For example, if you’re working with an API that sometimes returns garbled text data that isn’t decodable, and you want to show users a placeholder message instead of an error, then (1) gee, that’s weird, and (2) you can turn that one specific error into a success by adding a transformer:

    configure {
  $0.pipeline[.parsing].add(GarbledResponseHandler())
}

...

struct GarbledResponseHandler: ResponseTransformer {
  func process(_ response: Response) -> Response {
    switch response {
      case .success:
        return response

      case .failure(let error):
        if error.cause is RequestError.Cause.InvalidTextEncoding {
          return .success(Entity<Any>(
            content: "Nothingness. Tumbleweeds. The Void.",
            contentType: "text/string"))
        } else {
          return response
        }
    }
  }
}
    See more

    Declaration

    Swift

    public enum Cause
    Show on GitHub