HTTP Client errors docs for iOS (#5702)

Co-authored-by: Isabel <76437239+imatwawana@users.noreply.github.com>

src/platform-includes/getting-started-config/apple.mdx

@@ -16,6 +16,7 @@ func application(_ application: UIApplication,
         options.enableAppHangTracking = true
         options.enableFileIOTracking = true
         options.enableCoreDataTracking = true
+        options.enableCaptureFailedRequests = true
     }
 
     return true
@@ -35,6 +36,7 @@ func application(_ application: UIApplication,
         options.enableAppHangTracking = YES;
         options.enableFileIOTracking = YES;
         options.enableCoreDataTracking = YES;
+        options.enableCaptureFailedRequests = YES;
     }];
 
     return YES;
@@ -57,6 +59,7 @@ struct SwiftUIApp: App {
             options.enableAppHangTracking = true
             options.enableFileIOTracking = true
             options.enableCoreDataTracking = true
+            options.enableCaptureFailedRequests = true
         }
     }
 }

src/platform-includes/getting-started-primer/android.mdx

@@ -38,6 +38,7 @@ The SDK builds a crash report that persists to disk and tries to send the report
     - Apollo request spans with [Apollo Integration](/platforms/android/configuration/integrations/apollo/)
     - Distributed tracing through [OkHttp](/platforms/android/configuration/integrations/okhttp/) and [Apollo](/platforms/android/configuration/integrations/apollo/) integrations
 - [Application Not Responding (ANR)](/platforms/android/configuration/app-not-respond/) reported if the application is blocked for more than five seconds
+- [HTTP Client Errors](/platforms/android/configuration/integrations/okhttp/#http-client-errors)
 - Code samples provided in both Kotlin and Java as the Android SDK uses both languages
 - We provide a [sample application](https://github.com/getsentry/sentry-java/tree/master/sentry-samples/sentry-samples-android) for our Android users
 - Our [video tutorial](/platforms/android/android-video/) visually demonstrates how to set up our SDK

src/platform-includes/getting-started-primer/apple.mdx

@@ -11,6 +11,7 @@
   - Error messages of fatalError, assert, and precondition
   - [App Hang Detection](/platforms/apple/configuration/app-hangs/)
   - [Out of memory](/platforms/apple/configuration/out-of-memory/)
+  - [HTTP Client Errors](/platforms/apple/configuration/http-client-errors/)
   - Start-up crashes. The SDK init waits synchronously for up to 5 seconds to flush out events if the app crashes within 2 seconds after the SDK init.
 - Events [enriched](/platforms/apple/enriching-events/context/) with device data
 - Offline caching when a device is unable to connect; we send a report once we receive another event

src/platforms/apple/common/configuration/http-client-errors.mdx

@@ -0,0 +1,102 @@
+---
+title: HTTP Client Errors
+sidebar_order: 13
+description: "This feature, once enabled, automatically captures HTTP client errors, like bad response codes, as error events and reports them to Sentry"
+---
+
+Once enabled, this feature automatically captures HTTP client errors, like bad response codes, as error events and reports them to Sentry. The error event will contain the `request` and `response` data, such as `url`, `status_code`, and so on.
+
+Sending HTTP client errors is an opt-in feature and can be enabled by setting the `enableCaptureFailedRequests` option to `true`:
+
+```swift {tabTitle:Swift}
+import Sentry
+
+SentrySDK.start { options in
+    options.dsn = "___PUBLIC_DSN___"
+    options.enableCaptureFailedRequests = true
+}
+```
+
+```objc {tabTitle:Objective-C}
+@import Sentry;
+
+[SentrySDK startWithConfigureOptions:^(SentryOptions *options) {
+    options.dsn = @"___PUBLIC_DSN___";
+    options.enableCaptureFailedRequests = YES;
+}];
+```
+
+By default, only HTTP client errors with a response code between `500` and `599` are captured as error events, but you can change this behavior by setting the `failedRequestStatusCodes` option:
+
+```swift {tabTitle:Swift}
+import Sentry
+
+SentrySDK.start { options in
+    options.dsn = "___PUBLIC_DSN___"
+    let httpStatusCodeRange = HttpStatusCodeRange(min: 400, max: 599)
+    options.failedRequestStatusCodes = [ httpStatusCodeRange ]
+}
+```
+
+```objc {tabTitle:Objective-C}
+@import Sentry;
+
+[SentrySDK startWithConfigureOptions:^(SentryOptions *options) {
+    options.dsn = @"___PUBLIC_DSN___";
+    SentryHttpStatusCodeRange *httpStatusCodeRange =
+            [[SentryHttpStatusCodeRange alloc] initWithMin:400 max:599];
+    options.failedRequestStatusCodes = @[ httpStatusCodeRange ];
+}];
+```
+
+HTTP client errors from every target (`.*` regular expression) are automatically captured, but you can change this behavior by setting the `failedRequestTargets` option with either a regular expression or a plain `String`. A plain string must contain at least one of the items from the list. Plain strings don't have to be full matches, meaning the URL of a request is matched when it contains a string provided through the option:
+
+```swift {tabTitle:Swift}
+import Sentry
+
+SentrySDK.start { options in
+    options.dsn = "___PUBLIC_DSN___"
+    options.failedRequestTargets = [ "www.example.com" ]
+}
+```
+
+```objc {tabTitle:Objective-C}
+@import Sentry;
+
+[SentrySDK startWithConfigureOptions:^(SentryOptions *options) {
+    options.dsn = @"___PUBLIC_DSN___";
+    options.failedRequestTargets = @[ @"www.example.com" ];
+}];
+```
+
+Error events may contain PII data, such as `Headers` and `Cookies`. Sentry already does data scrubbing by default, but you can scrub any data before it is sent. Learn more in [Scrubbing Sensitive Data](/platforms/apple/guides/ios/data-management/sensitive-data/).
+
+These events are searchable and you can set alerts on them if you use the `http.url` and `http.status_code` properties. Learn more in our full [Searchable Properties](/product/sentry-basics/search/searchable-properties/) documentation.
+
+### Customize or Drop the Error Event
+
+The captured error event can be customized or dropped with a `beforeSend`:
+
+```swift {tabTitle:Swift}
+import Sentry
+
+SentrySDK.start { options in
+    options.dsn = "___PUBLIC_DSN___"
+    options.beforeSend = { event in
+        // modify event here or return NULL to discard the event
+        return event
+    }
+}
+```
+
+```objc {tabTitle:Objective-C}
+@import Sentry;
+
+[SentrySDK startWithConfigureOptions:^(SentryOptions *options) {
+    options.dsn = @"___PUBLIC_DSN___";
+    options.beforeSend = ^SentryEvent * _Nullable(SentryEvent * _Nonnull event) {
+        // modify event here or return NULL to discard the event
+        return event;
+    }
+}];
+```

src/platforms/apple/common/configuration/swizzling.mdx

@@ -12,6 +12,7 @@ __macOS__
 - <PlatformLink to="/performance/instrumentation/automatic-instrumentation/#file-io-tracking">Auto instrumentation for File I/O operations</PlatformLink>
 - <PlatformLink to="/performance/instrumentation/automatic-instrumentation/#core-data-tracking">Auto instrumentation for Core Data operations</PlatformLink>
 - <PlatformLink to="/performance/connect-services/">Automatically added sentry-trace header to HTTP requests for distributed tracing</PlatformLink>
+- <PlatformLink to="/configuration/http-client-errors/">HTTP Client Errors</PlatformLink>
 
 
 __iOS, tvOS and Catalyst__
@@ -23,6 +24,7 @@ __iOS, tvOS and Catalyst__
 - <PlatformLink to="/performance/instrumentation/automatic-instrumentation/#core-data-tracking">Auto instrumentation for Core Data operations</PlatformLink>
 - <PlatformLink to="/performance/connect-services/">Automatically added sentry-trace header to HTTP requests for distributed tracing</PlatformLink>
 - <PlatformLink to="/performance/instrumentation/automatic-instrumentation/#user-interaction-tracing">User interaction transactions for UI clicks (experimental)</PlatformLink>
+- <PlatformLink to="/configuration/http-client-errors/">HTTP Client Errors</PlatformLink>
 
 Since Cocoa 7.5.0, you can opt out of swizzling using options. When you disable swizzling, the SDK disables the features above:
 

src/platforms/common/configuration/options.mdx

@@ -507,6 +507,18 @@ _(New in version 6.6.0)_
 
 </ConfigKey>
 
+<ConfigKey name="capture-failed-requests" supported={["apple"]}>
+
+Once enabled, this feature automatically captures HTTP client errors, like bad response codes, as error events and reports them to Sentry.
+
+<PlatformSection supported={["apple"]}>
+
+_(New in version 7.30.0)_
+
+</PlatformSection>
+
+</ConfigKey>
+
 <PlatformSection supported={["javascript", "python", "node", "dart", "java", "apple"]}>
 
 ## Integration Configuration

src/wizard/apple/ios.md

@@ -42,6 +42,7 @@ func application(_ application: UIApplication,
         options.enableAppHangTracking = true
         options.enableFileIOTracking = true
         options.enableCoreDataTracking = true
+        options.enableCaptureFailedRequests = true
     }
 
     return true
@@ -68,6 +69,7 @@ struct SwiftUIApp: App {
             options.enableAppHangTracking = true
             options.enableFileIOTracking = true
             options.enableCoreDataTracking = true
+            options.enableCaptureFailedRequests = true
         }
     }
 }