From 7a3160b4e750fe230ef0b6c2225c0644608e5138 Mon Sep 17 00:00:00 2001 From: Giannis Gkiortzis <58184179+giortzisg@users.noreply.github.com> Date: Thu, 5 Feb 2026 16:54:22 +0100 Subject: [PATCH 1/3] feat(develop): client report handling of HTTP 413 --- develop-docs/sdk/telemetry/client-reports.mdx | 25 ++++++++++++------- 1 file changed, 16 insertions(+), 9 deletions(-) diff --git a/develop-docs/sdk/telemetry/client-reports.mdx b/develop-docs/sdk/telemetry/client-reports.mdx index 1988479ea7839..68c5c1ba7f952 100644 --- a/develop-docs/sdk/telemetry/client-reports.mdx +++ b/develop-docs/sdk/telemetry/client-reports.mdx @@ -157,15 +157,22 @@ SDKs **SHOULD** minimize unnecessary HTTP requests and **MUST NOT** send an enve SDKs **MAY** keep track of discarded events in the transport. Once SDKs implement the [telemetry processor](/sdk/telemetry/telemetry-processor/), they **SHOULD** implement client reports tracking outside the transport, since data can be dropped in multiple places throughout the SDK. The [telemetry scheduler](/sdk/telemetry/telemetry-processor/#telemetry-scheduler) is then responsible for passing aggregated client reports to the transport. The telemetry scheduler still **MUST** adhere to the requirements above. -The one who drops an envelope item must record and report it. If the server drops -an envelope item, for example, with the response 429, the client SDK must not record -this as the server already does. Still, the SDK must record lost envelope items -when dropping them itself, for example, caused by an active rate limit. SDKs can put -a simple optional check for HTTP status codes in place where any code `>= 400` except -`429` will be recorded as `send_error`. The client SDKs can assume that client -reports never get rate limited. The server is minimizing the possibility of client -reports getting rate limited, but the SDKs shouldn't worry about this edge case as -this feature is best-effort. + +### Dealing with network failures + +The party that drops an envelope item **MUST** record and report it. + +The `send_error` reason is reserved for client error outcomes only. Server related codes **SHOULD NOT** be recorded since the server already tracks these. However, Relay does not always record an outcome for oversized envelopes (413), so SDKs **SHOULD** accept the trade-off of potential double counting for `RequestEntityTooLarge` (413) responses to ensure all discarded events are captured. `TooManyRequests` (429) responses **MUST** be skipped since the server records these outcomes. + +In summary: + +- **HTTP 2xx**: Successful send—no client report needed. +- **HTTP 4xx/5xx (except 429)**: Discard the envelope and record a client report with reason `send_error`. +- **HTTP 429**: Discard the envelope without recording a client report. + +SDKs can assume client reports are never rate limited. + +For more details on retry behavior and error handling, see [Dealing with Network Failures](/sdk/expected-features/#dealing-with-network-failures). ### Configuration From 99a702336b059befe1b8b9001223a96817cad257 Mon Sep 17 00:00:00 2001 From: Giannis Gkiortzis <58184179+giortzisg@users.noreply.github.com> Date: Fri, 6 Feb 2026 11:29:38 +0100 Subject: [PATCH 2/3] chore: link only the network failures page --- develop-docs/sdk/telemetry/client-reports.mdx | 16 +++------------- 1 file changed, 3 insertions(+), 13 deletions(-) diff --git a/develop-docs/sdk/telemetry/client-reports.mdx b/develop-docs/sdk/telemetry/client-reports.mdx index 68c5c1ba7f952..273de01eec2da 100644 --- a/develop-docs/sdk/telemetry/client-reports.mdx +++ b/develop-docs/sdk/telemetry/client-reports.mdx @@ -158,21 +158,11 @@ SDKs **SHOULD** minimize unnecessary HTTP requests and **MUST NOT** send an enve SDKs **MAY** keep track of discarded events in the transport. Once SDKs implement the [telemetry processor](/sdk/telemetry/telemetry-processor/), they **SHOULD** implement client reports tracking outside the transport, since data can be dropped in multiple places throughout the SDK. The [telemetry scheduler](/sdk/telemetry/telemetry-processor/#telemetry-scheduler) is then responsible for passing aggregated client reports to the transport. The telemetry scheduler still **MUST** adhere to the requirements above. -### Dealing with network failures +### Dealing with Network Failures -The party that drops an envelope item **MUST** record and report it. +The party that drops an envelope item **MUST** record and report it. SDKs can assume client reports are never rate limited. -The `send_error` reason is reserved for client error outcomes only. Server related codes **SHOULD NOT** be recorded since the server already tracks these. However, Relay does not always record an outcome for oversized envelopes (413), so SDKs **SHOULD** accept the trade-off of potential double counting for `RequestEntityTooLarge` (413) responses to ensure all discarded events are captured. `TooManyRequests` (429) responses **MUST** be skipped since the server records these outcomes. - -In summary: - -- **HTTP 2xx**: Successful send—no client report needed. -- **HTTP 4xx/5xx (except 429)**: Discard the envelope and record a client report with reason `send_error`. -- **HTTP 429**: Discard the envelope without recording a client report. - -SDKs can assume client reports are never rate limited. - -For more details on retry behavior and error handling, see [Dealing with Network Failures](/sdk/expected-features/#dealing-with-network-failures). +For details on which HTTP status codes require a client report and which discard reasons to use, see [Dealing with Network Failures](/sdk/expected-features/#dealing-with-network-failures). ### Configuration From 1357d78be5decc2cf289cbeba8c228317a27e78a Mon Sep 17 00:00:00 2001 From: Giannis Gkiortzis <58184179+giortzisg@users.noreply.github.com> Date: Fri, 6 Feb 2026 11:44:38 +0100 Subject: [PATCH 3/3] chore: add more details --- develop-docs/sdk/telemetry/client-reports.mdx | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/develop-docs/sdk/telemetry/client-reports.mdx b/develop-docs/sdk/telemetry/client-reports.mdx index 273de01eec2da..6cfbfbbf14461 100644 --- a/develop-docs/sdk/telemetry/client-reports.mdx +++ b/develop-docs/sdk/telemetry/client-reports.mdx @@ -157,10 +157,7 @@ SDKs **SHOULD** minimize unnecessary HTTP requests and **MUST NOT** send an enve SDKs **MAY** keep track of discarded events in the transport. Once SDKs implement the [telemetry processor](/sdk/telemetry/telemetry-processor/), they **SHOULD** implement client reports tracking outside the transport, since data can be dropped in multiple places throughout the SDK. The [telemetry scheduler](/sdk/telemetry/telemetry-processor/#telemetry-scheduler) is then responsible for passing aggregated client reports to the transport. The telemetry scheduler still **MUST** adhere to the requirements above. - -### Dealing with Network Failures - -The party that drops an envelope item **MUST** record and report it. SDKs can assume client reports are never rate limited. +The party that drops an envelope item **MUST** record and report it. SDKs can assume client reports are never rate limited. The server is minimizing the possibility of client reports getting rate limited, but the SDKs shouldn't worry about this edge case as this feature is best-effort. For details on which HTTP status codes require a client report and which discard reasons to use, see [Dealing with Network Failures](/sdk/expected-features/#dealing-with-network-failures).