---
title: "Offline Caching"
description: "How SDKs buffer envelopes to disk for retry when network connectivity is unavailable, and how to handle network failure responses."
url: https://develop.sentry.dev/sdk/foundations/transport/offline-caching/
---

# Offline Caching

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.

## [Overview](https://develop.sentry.dev/sdk/foundations/transport/offline-caching.md#overview)

Also known as "Buffer to Disk". SDKs write envelopes to disk before attempting to send, so that they can be retried in the event of a temporary network failure. SDKs **MUST** implement a cap on the number of stored envelopes. This feature is mostly useful on mobile and desktop apps, where stable connectivity is often not available.

## [Dealing With Network Failures](https://develop.sentry.dev/sdk/foundations/transport/offline-caching.md#dealing-with-network-failures)

When SDKs receive an `HTTP 2xx` status code response from Sentry, they **MUST** consider it as a successful send.

If Sentry returns an `HTTP 4xx` or `HTTP 5xx` status code, SDKs **MUST** discard the envelope and record a [client report](https://develop.sentry.dev/sdk/telemetry/client-reports.md#network-failure-recording) as specified in the client reports spec.

### [HTTP 413 Content Too Large](https://develop.sentry.dev/sdk/foundations/transport/offline-caching.md#http-413-content-too-large)

For an [`HTTP 413 Content Too Large`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/413) response, SDKs:

* **MUST** discard the envelope and record a [client report](https://develop.sentry.dev/sdk/telemetry/client-reports.md#network-failure-recording).
* **MUST NOT** retry sending the envelope.
* **SHOULD** log an error, informing users that the envelope was discarded due to size limits.
* **MAY** add information from the response body to the logged error. If doing so, SDKs **MUST** be aware that Relay can change or remove information in the response body for an `HTTP 413` at any time without notice.

### [HTTP 429 Too Many Requests](https://develop.sentry.dev/sdk/foundations/transport/offline-caching.md#http-429-too-many-requests)

For an [`HTTP 429 Too Many Requests`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429) response, SDKs:

* **MUST** respect the [rate limiting rules](https://develop.sentry.dev/sdk/foundations/transport/rate-limiting.md), such as correctly parsing the retry-header.
* **MUST** discard the envelope, but **MUST NOT** record a [client report](https://develop.sentry.dev/sdk/telemetry/client-reports.md#network-failure-recording), because the upstream already does this.
* **MUST NOT** retry sending the envelope.

### [Network Errors](https://develop.sentry.dev/sdk/foundations/transport/offline-caching.md#network-errors)

SDKs **MAY** retry sending the envelope when a network error occurs, such as:

* Connection timeout
* DSN resolution failure
* Connection reset by peer

When other failures occur, like those caused by processing the file in the SDK itself, SDKs **MUST** discard the envelope and record a [client report](https://develop.sentry.dev/sdk/telemetry/client-reports.md#network-failure-recording) with the discard reason `internal_sdk_error`. Otherwise, the SDK might end up in an endless retry loop.

See the [Client Reports — Network Failure Recording](https://develop.sentry.dev/sdk/telemetry/client-reports.md#network-failure-recording) spec for the full set of client report recording requirements for each HTTP status code.

## [Additional Capabilities](https://develop.sentry.dev/sdk/foundations/transport/offline-caching.md#additional-capabilities)

SDKs **SHOULD** retry sending envelopes once the device is back online, when such notification exists in the platform.

Once the device is back online, the SDK is likely going to empty its disk queue in a quick burst of requests. This can trigger abuse filters in Sentry. To account for that, SDKs **SHOULD** add a small delay between cached envelope sends. A recommended value is 100 milliseconds.

If the SDK is being [rate-limited](https://develop.sentry.dev/sdk/foundations/transport/rate-limiting.md), which causes the SDK to drop any envelope that reaches its HTTP transport, SDKs **SHOULD** stop consuming the disk cache until the `Retry-After` timeout is reached or the app restarts.

## [Example Implementations](https://develop.sentry.dev/sdk/foundations/transport/offline-caching.md#example-implementations)

* [C#](https://github.com/getsentry/sentry-dotnet/blob/main/src/Sentry/Internal/Http/CachingTransport.cs)
* [Java](https://github.com/getsentry/sentry-java/blob/main/sentry/src/main/java/io/sentry/cache/EnvelopeCache.java)
* [Objective-C](https://github.com/getsentry/sentry-cocoa/blob/master/Sources/Sentry/SentryHttpTransport.m)
* [TypeScript](https://github.com/getsentry/sentry-electron/blob/master/src/main/transports/electron-offline-net.ts)