From a3361fe1df1ada26a759e96db532e7bddaa4e1f1 Mon Sep 17 00:00:00 2001 From: Philipp Hofmann Date: Thu, 4 Dec 2025 12:06:41 +0100 Subject: [PATCH 1/4] fix: Network failures drop envelope on 429 Clarify that SDKs must also drop envelopes on 429 responses. --- develop-docs/sdk/expected-features/index.mdx | 11 ++++++++++- 1 file changed, 10 insertions(+), 1 deletion(-) diff --git a/develop-docs/sdk/expected-features/index.mdx b/develop-docs/sdk/expected-features/index.mdx index 1df0b5c7db6e4..b47e7df23219a 100644 --- a/develop-docs/sdk/expected-features/index.mdx +++ b/develop-docs/sdk/expected-features/index.mdx @@ -251,7 +251,16 @@ Write events to disk before attempting to send, so that they can be retried in t ### 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` (excluding `HTTP 429`) or `HTTP 5xx` status code, SDKs **MUST** discard the envelope and record a [client report](/sdk/telemetry/client-reports) with the discard reason `send_error`. For an `HTTP 429` response, SDKs **MUST NOT** record a client report to comply with the [rate limiting](/sdk/expected-features/rate-limiting/) rules, because the backend already records a client report for the rate limit. SDKs **MAY** retry sending the envelope when a network error occurs, such as: +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](/sdk/telemetry/client-reports) with the discard reason `send_error`. + +For an `HTTP 429` response, SDKs: + +- **MUST** respect the [rate limiting rules](/sdk/expected-features/rate-limiting/), such as correctly parsing the retry-header +- **MUST** drop the envelope, but **MUST NOT** record a [client report](/sdk/telemetry/client-reports), because the backend already does this. Doing this would double-count dropped envelopes. + +SDKs **MAY** retry sending the envelope when a network error occurs, such as: * Connection timeout * DSN resolution failure From ab07b161da776e7e9357c695878d8c748026192d Mon Sep 17 00:00:00 2001 From: Philipp Hofmann Date: Thu, 4 Dec 2025 12:08:29 +0100 Subject: [PATCH 2/4] even more clear --- develop-docs/sdk/expected-features/index.mdx | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/develop-docs/sdk/expected-features/index.mdx b/develop-docs/sdk/expected-features/index.mdx index b47e7df23219a..f899279cb59d8 100644 --- a/develop-docs/sdk/expected-features/index.mdx +++ b/develop-docs/sdk/expected-features/index.mdx @@ -257,8 +257,9 @@ If Sentry returns an `HTTP 4xx` or `HTTP 5xx` status code, SDKs **MUST** discard For an `HTTP 429` response, SDKs: -- **MUST** respect the [rate limiting rules](/sdk/expected-features/rate-limiting/), such as correctly parsing the retry-header +- **MUST** respect the [rate limiting rules](/sdk/expected-features/rate-limiting/), such as correctly parsing the retry-header. - **MUST** drop the envelope, but **MUST NOT** record a [client report](/sdk/telemetry/client-reports), because the backend already does this. Doing this would double-count dropped envelopes. +- **MUST NOT** retry sending the envelope. SDKs **MAY** retry sending the envelope when a network error occurs, such as: From afecb9b3b4a7f5fb1d01ad9ed77c15c107939284 Mon Sep 17 00:00:00 2001 From: Philipp Hofmann Date: Thu, 4 Dec 2025 12:12:14 +0100 Subject: [PATCH 3/4] AI feedback --- develop-docs/sdk/expected-features/index.mdx | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/develop-docs/sdk/expected-features/index.mdx b/develop-docs/sdk/expected-features/index.mdx index f899279cb59d8..6b743b9a36bbb 100644 --- a/develop-docs/sdk/expected-features/index.mdx +++ b/develop-docs/sdk/expected-features/index.mdx @@ -253,7 +253,10 @@ Write events to disk before attempting to send, so that they can be retried in t 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](/sdk/telemetry/client-reports) with the discard reason `send_error`. +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 429` responses, see below. For an `HTTP 429` response, SDKs: From 73dbc521b437ecd57427c7059f73e7c8266b11cf Mon Sep 17 00:00:00 2001 From: Philipp Hofmann Date: Wed, 10 Dec 2025 08:23:55 +0100 Subject: [PATCH 4/4] Update develop-docs/sdk/expected-features/index.mdx Co-authored-by: Markus Hintersteiner --- develop-docs/sdk/expected-features/index.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/develop-docs/sdk/expected-features/index.mdx b/develop-docs/sdk/expected-features/index.mdx index 6b743b9a36bbb..39b206fcdb9d5 100644 --- a/develop-docs/sdk/expected-features/index.mdx +++ b/develop-docs/sdk/expected-features/index.mdx @@ -255,7 +255,7 @@ 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** discard the envelope - **MUST** record a [client report](/sdk/telemetry/client-reports) with the discard reason `send_error`, except for `HTTP 429` responses, see below. For an `HTTP 429` response, SDKs: