diff --git a/develop-docs/sdk/expected-features/index.mdx b/develop-docs/sdk/expected-features/index.mdx index a4fbbb956a0fb1..8309c5ad123bfa 100644 --- a/develop-docs/sdk/expected-features/index.mdx +++ b/develop-docs/sdk/expected-features/index.mdx @@ -256,11 +256,11 @@ When SDKs receive an `HTTP 2xx` status code response from Sentry, they **MUST** If Sentry returns an `HTTP 4xx` or `HTTP 5xx` status code, SDKs: - **MUST** discard the envelope -- **MUST** record a [client report](/sdk/telemetry/client-reports) with the discard reason `send_error`, except for `HTTP 413` and `HTTP 429` responses, see below. +- **MUST** record a [client report](/sdk/telemetry/client-reports) with the discard reason `send_error`, except for an `HTTP 429` response, see below. For an [`HTTP 413 Content Too Large`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/413) response, SDKs: -* **MUST** discard the envelope, but **MUST NOT** record a [client report](/sdk/telemetry/client-reports), because the upstream already does this. Doing this would double-count client reports for discarded envelopes. +* **MUST** discard the envelope and record a [client report](/sdk/telemetry/client-reports) with the discard reason `send_error`. Upstream usually records a [client report](/sdk/telemetry/client-reports) for oversized envelopes, but not always. Double-counting is preferable to not counting, so users are aware of all dropped envelopes. Since client reports are not expected to be fully accurate, we accept this tradeoff for now (Jan 7th 2026). In the future, we may add error responses to indicate when SDKs should 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 413` at any time without notice.