---
title: "HTTP Client"
description: "Guidelines for HTTP client integrations — breadcrumbs, spans, trace headers, DSN exclusion, and automatic error capture."
url: https://develop.sentry.dev/sdk/foundations/client/integrations/http-client/
---

# HTTP Client

This document uses key words such as "MUST", "SHOULD", and "MAY" as defined in

<!-- -->

[RFC 2119](https://www.ietf.org/rfc/rfc2119.txt) to indicate requirement levels.

Statusstable

Version`1.0.0`[(changelog)](https://develop.sentry.dev/sdk/foundations/client/integrations/http-client.md#changelog)

## [Overview](https://develop.sentry.dev/sdk/foundations/client/integrations/http-client.md#overview)

HTTP client integrations instrument outgoing HTTP requests to capture breadcrumbs, create performance spans, and optionally capture HTTP client errors as Sentry events.

Every HTTP client integration **MUST** exclude HTTP requests that match the configured DSN in the Options to exclude HTTP requests to Sentry.

***

## [Behavior](https://develop.sentry.dev/sdk/foundations/client/integrations/http-client.md#behavior)

### [Breadcrumbs](https://develop.sentry.dev/sdk/foundations/client/integrations/http-client.md#breadcrumbs)

Stablespecified since

<!-- -->

1.0.0

Add a breadcrumb for each outgoing HTTP request after the request finishes:

* type: `http`

* category: `http`

* level

  * `info` - response status code 2XX - 3XX
  * `warning` - response status code 4XX
  * `error` - response status code 5XX

* data (all fields are optional but recommended):

  * `url` - The URL used in the HTTP request
  * `http.request.method` - uppercase HTTP method, i.e: GET, HEAD
  * `http.response.status_code` - Numeric status code such as `200` or `404`
  * `http.query` - The query part of the URL
  * `http.fragment` - The fragment part of the URI (Browser SDKs only)
  * `http.request.body.size` Size in bytes
  * `http.response.body.size` Size in bytes

### [Performance Spans](https://develop.sentry.dev/sdk/foundations/client/integrations/http-client.md#performance-spans)

Stablespecified since

<!-- -->

1.0.0

If Performance Monitoring is both supported by the SDK and enabled in the client application when the transaction is active a new `Span` must be created around the HTTP request:

* operation: `http.client`
* description: `$METHOD $url` (uppercase HTTP method), e.g. `GET https://sentry.io`
* HTTP requests must be enhanced with a [`sentry-trace` HTTP header](https://develop.sentry.dev/sdk/foundations/trace-propagation.md#sentry-trace-header) to support [distributed tracing](https://docs.sentry.io/product/sentry-basics/tracing/distributed-tracing)
* HTTP requests must be enhanced with a [`baggage` HTTP header](https://develop.sentry.dev/sdk/foundations/trace-propagation/dynamic-sampling-context.md#baggage-header) to support [dynamic sampling](https://develop.sentry.dev/sdk/foundations/trace-propagation/dynamic-sampling-context.md)
* span status must match HTTP response status code ([see Span status to HTTP status code mapping](https://develop.sentry.dev/sdk/foundations/transport/event-payloads/span.md))
* when network error occurs, span status must be set to `internal_error`
* span data must follow the [Span Data Conventions](https://develop.sentry.dev/sdk/telemetry/traces/span-data-conventions.md)

### [HTTP Client Errors](https://develop.sentry.dev/sdk/foundations/client/integrations/http-client.md#http-client-errors)

Stablespecified since

<!-- -->

1.0.0

The SDK automatically captures HTTP Client errors and sends them to [sentry.io](https://sentry.io).

The HTTP Client integration should have 3 configuration options:

* `captureFailedRequests` defaults to `false` when introducing this feature due to PII reasons and can be changed to `true` in a follow up major.
  * The SDK will only capture HTTP Client errors if it is enabled.

* `failedRequestStatusCodes` defaults to `500 - 599`, this configuration option accepts a `List` of `HttpStatusCodeRange` which is a range of HTTP status code -> `min` to `max` or a single `status_code`.

  * The SDK will only capture HTTP Client errors if the HTTP Response status code is within the defined ranges in `failedRequestStatusCodes`.
  * If the language has a `Range` type, it should be used instead of `HttpStatusCodeRange`.

* `failedRequestTargets` defaults to (`.*`), this configuration option accepts a `List` of `String` that may be Regular expressions as well, similar to [tracePropagationTargets](https://develop.sentry.dev/sdk/foundations/trace-propagation.md#trace-propagation-targets).
  * The SDK will only capture HTTP Client errors if the HTTP Request URL is a match for any of the `failedRequestsTargets`.

* While the keys of sensitive HTTP headers (e.g. `Authorization` and `Cookie`) are included, their values must be replaced with `"[Filtered]"` (also see [Data Handling: Sensitive Data](https://develop.sentry.dev/sdk/foundations/data-scrubbing.md#sensitive-data)).

The HTTP Client integration should capture error events with the following properties:

The Request interface, see the [Spec](https://develop.sentry.dev/sdk/foundations/transport/event-payloads/request.md) for details.

The Response context, see the [Spec](https://develop.sentry.dev/sdk/foundations/transport/event-payloads/contexts.md#response-context) for details.

```json
{
  "contexts": {
    "response": {
      "type": "response",
      "cookies": "PHPSESSID=298zf09hf012fh2; csrftoken=u32t4o3tb3gg43; _gat=1;",
      "headers": {
        "content-type": "text/html"
        /// ...
      },
      "status_code": 500,
      "body_size": 1000 // in bytes
    }
  }
}
```

The Exception Interface, see the [Errors spec](https://develop.sentry.dev/sdk/telemetry/errors.md) for details.

If the HTTP Client integration does not throw an exception for unsuccessful requests, you can create a synthetic exception following this spec:

* Set the [Exception Mechanism](https://develop.sentry.dev/sdk/telemetry/errors.md#exception-mechanism) with a proper `type` such as `SentryOkHttpInterceptor`.
* Set the [Stack Trace Interface](https://develop.sentry.dev/sdk/foundations/transport/event-payloads/stacktrace.md) with `snapshot=true`.
  * `HTTP Client Error with status code: $code`.

When capturing error events, pass the original `Request` and `Response` objects from the HTTP Client as `hints`, so the users may filter out events in `beforeSend` with the full context.

Automatically captured HTTP Client error events can be searchable and alertable with the `http.url` and `http.status_code` properties, learn more about it in the [Searchable Properties](https://docs.sentry.io/concepts/search/searchable-properties/) docs.

As an example, see the [OkHTTP Client integration](https://github.com/getsentry/sentry-java/pull/2287) for Android.

***

## [Changelog](https://develop.sentry.dev/sdk/foundations/client/integrations/http-client.md#changelog)

| Version | Date       | Summary                                        |
| ------- | ---------- | ---------------------------------------------- |
| `1.0.0` | 2025-02-24 | Initial spec, extracted from expected features |