Transport

The transport layer handles all communication between an SDK and the Sentry server. SDKs serialize data into envelopes, authenticate requests using DSN-derived credentials, optionally compress payloads, respect rate limits communicated via response headers, and optionally buffer envelopes to disk for retry on network failure.

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.

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

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

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

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/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.