Offline Caching
How SDKs buffer envelopes to disk for retry when network connectivity is unavailable, and how to handle network failure responses.
This document uses key words such as "MUST", "SHOULD", and "MAY" as defined in RFC 2119 to indicate requirement levels.
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.
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 as specified in the client reports spec.
For an HTTP 413 Content Too Large response, SDKs:
- MUST discard the envelope and record a client report.
- 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 413at any time without notice.
For an HTTP 429 Too Many Requests response, SDKs:
- MUST respect the rate limiting rules, such as correctly parsing the retry-header.
- MUST discard the envelope, but MUST NOT record a client report, because the upstream already does this.
- MUST NOT retry sending the envelope.
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 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 spec for the full set of client report recording requirements for each HTTP status code.
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, 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.
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").