---
title: "Transport"
description: "How SDKs send data to Sentry - envelope format, authentication, compression, and rate limiting."
url: https://develop.sentry.dev/sdk/foundations/transport/
---

# Transport

The transport layer handles all communication between an SDK and the Sentry server. SDKs serialize data into [envelopes](https://develop.sentry.dev/sdk/foundations/transport/envelopes.md), [authenticate](https://develop.sentry.dev/sdk/foundations/transport/authentication.md) requests using DSN-derived credentials, optionally [compress](https://develop.sentry.dev/sdk/foundations/transport/compression.md) payloads, respect [rate limits](https://develop.sentry.dev/sdk/foundations/transport/rate-limiting.md) communicated via response headers, and optionally [buffer envelopes to disk](https://develop.sentry.dev/sdk/foundations/transport/offline-caching.md) for retry on network failure.

## [Background Sending](https://develop.sentry.dev/sdk/foundations/transport.md#background-sending)

Envelopes **SHOULD** be transmitted in a background thread or equivalent asynchronous mechanism so that sending does not block the application. The send queue **MUST** be flushed when the application shuts down, with a configurable timeout. This is typically exposed to users as [shutdown and draining](https://docs.sentry.io/platforms/javascript/configuration/draining/).

## [HTTP Proxy](https://develop.sentry.dev/sdk/foundations/transport.md#http-proxy)

SDKs **SHOULD** support routing requests through an HTTP proxy. The proxy **SHOULD** be configurable via a `proxy` option in `Sentry.init()` and **SHOULD** also be picked up from the system environment when not explicitly configured.

SDKs **SHOULD** respect the following environment variables, in order of precedence:

1. `options.proxy` — explicit SDK configuration (highest priority)
2. `https_proxy` — for HTTPS requests to Sentry
3. `http_proxy` — fallback for all requests
4. `no_proxy` — comma-separated list of hostnames that bypass the proxy

When a proxy is configured, the SDK **MUST** use it for all outgoing requests to Sentry. When `no_proxy` matches the Sentry hostname, the proxy **MUST** be bypassed.

SDKs **MAY** support proxy authentication (username/password) and custom CA certificates for secure proxy connections.

## [Reading the Response](https://develop.sentry.dev/sdk/foundations/transport.md#reading-the-response)

On success, you will receive an HTTP response from the server containing a JSON payload with information on the submitted payload:

```http
HTTP/1.1 200 OK
Content-Type: application/json

{
  "id": "fc6d8c0c43fc4630ad850ee518f1b9d0"
}
```

**Always** check for a `200` response, which confirms the message was delivered. A small level of validation happens immediately that may result in a different response code (and message).

## [Handling Server Errors](https://develop.sentry.dev/sdk/foundations/transport.md#handling-server-errors)

SDKs **MUST** honor the `429` status code and not attempt sending until the `Retry-After` kicks in. SDKs **SHOULD** drop events if Sentry is unavailable instead of retrying.

To debug an error during development, inspect the response headers and response body. For example, you may get a response similar to:

```http
HTTP/1.1 400 Bad Request
Content-Type: application/json
X-Sentry-Error: failed to read request body

{
  "detail":"failed to read request body",
  "causes":[
    "failed to decode zlib payload",
    "corrupt deflate stream"
  ]
}
```

The `X-Sentry-Error` header and response body will not always contain a message, but they can still be helpful in debugging clients. When emitted, they will contain a precise error message, which is useful to identify root cause.

##### Note

We do not recommend that SDKs retry event submissions automatically on error — not even if `Retry-After` is declared in the response headers. If a request fails once, it is very likely to fail again on the next attempt. Retrying too often may cause further rate limiting or blocking by the Sentry server.

* #### [Authentication](https://develop.sentry.dev/sdk/foundations/transport/authentication.md)

  DSN format, authentication headers, and HTTP conventions for communicating with Sentry.

* #### [Compression](https://develop.sentry.dev/sdk/foundations/transport/compression.md)

  Request compression and transfer encoding for Sentry envelope submissions.

* #### [Offline Caching](https://develop.sentry.dev/sdk/foundations/transport/offline-caching.md)

  How SDKs buffer envelopes to disk for retry when network connectivity is unavailable, and how to handle network failure responses.

* #### [Rate Limiting](https://develop.sentry.dev/sdk/foundations/transport/rate-limiting.md)

* #### [Envelopes](https://develop.sentry.dev/sdk/foundations/transport/envelopes.md)

* #### [Envelope Items](https://develop.sentry.dev/sdk/foundations/transport/envelope-items.md)

* #### [Event Payloads](https://develop.sentry.dev/sdk/foundations/transport/event-payloads.md)

## Pages in this section

- [Authentication](https://develop.sentry.dev/sdk/foundations/transport/authentication.md)
- [Compression](https://develop.sentry.dev/sdk/foundations/transport/compression.md)
- [Offline Caching](https://develop.sentry.dev/sdk/foundations/transport/offline-caching.md)
- [Rate Limiting](https://develop.sentry.dev/sdk/foundations/transport/rate-limiting.md)
- [Envelopes](https://develop.sentry.dev/sdk/foundations/transport/envelopes.md)
- [Envelope Items](https://develop.sentry.dev/sdk/foundations/transport/envelope-items.md)
- [Event Payloads](https://develop.sentry.dev/sdk/foundations/transport/event-payloads.md)