From 6185df7815525279de4b0cd356ff648dbaf4278f Mon Sep 17 00:00:00 2001 From: Philipp Hofmann Date: Thu, 20 Nov 2025 08:54:12 +0100 Subject: [PATCH 1/4] fix(develop-docs): Handling 400s in transport Make it clearer that SDKS must drop envelopes when getting a 4xx response and SDKs must record client reports in that scenario. --- develop-docs/sdk/expected-features/index.mdx | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/develop-docs/sdk/expected-features/index.mdx b/develop-docs/sdk/expected-features/index.mdx index 2e6372a2b8a14..bacd82a58960a 100644 --- a/develop-docs/sdk/expected-features/index.mdx +++ b/develop-docs/sdk/expected-features/index.mdx @@ -251,14 +251,13 @@ Write events to disk before attempting to send, so that they can be retried in t ### Dealing With Network Failures -An `HTTP 2xx` status code response from Sentry is considered a successful send. It's important to note that retry is only considered in the event of a network failure. For example: +When SDKs receive an `HTTP 2xx` status code response from Sentry, they **MUST** consider it as a successful send. If Sentry returns a `HTTP 4xx or 5xx` status code, SDKs **MUST** discard the envelope and record a [client report](/sdk/telemetry/client-reports] with the discard reason `send_error`. SDKs **MAY** retry sending the envelope when a network error occurs, such as: * Connection timeout * DSN resolution failure * Connection reset by peer -Other failures, like those caused by processing the file in the SDK itself, the payload should be discarded since those are likely to end up on an endless retry. -If the event reached Sentry and an HTTP response status code was received, even in the event of an `HTTP 500` status code, the event should be discarded. +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](/sdk/telemetry/client-reports) with the discard reason `internal_sdk_error`. Otherwise, the SDK might end up in an endless retry loop. #### Additional capabilities From 2b379fe6f549278930f280cce5ac1d4eba4ff7b1 Mon Sep 17 00:00:00 2001 From: Philipp Hofmann Date: Thu, 20 Nov 2025 09:06:06 +0100 Subject: [PATCH 2/4] fix link --- 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 bacd82a58960a..9440512c04ce7 100644 --- a/develop-docs/sdk/expected-features/index.mdx +++ b/develop-docs/sdk/expected-features/index.mdx @@ -251,7 +251,7 @@ 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 a `HTTP 4xx or 5xx` status code, SDKs **MUST** discard the envelope and record a [client report](/sdk/telemetry/client-reports] with the discard reason `send_error`. 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 a `HTTP 4xx or 5xx` status code, SDKs **MUST** discard the envelope and record a [client report](/sdk/telemetry/client-reports) with the discard reason `send_error`. SDKs **MAY** retry sending the envelope when a network error occurs, such as: * Connection timeout * DSN resolution failure From 57a29fe9a1fd32ed0bf3e5967311d63b71f1b85b Mon Sep 17 00:00:00 2001 From: Philipp Hofmann Date: Thu, 20 Nov 2025 09:08:21 +0100 Subject: [PATCH 3/4] cursor feedback --- 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 9440512c04ce7..28e4e0e892169 100644 --- a/develop-docs/sdk/expected-features/index.mdx +++ b/develop-docs/sdk/expected-features/index.mdx @@ -251,7 +251,7 @@ 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 a `HTTP 4xx or 5xx` status code, SDKs **MUST** discard the envelope and record a [client report](/sdk/telemetry/client-reports) with the discard reason `send_error`. 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` (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** apply the [rate limiting](/sdk/expected-features/rate-limiting/) rules, discard the envelope without recording a client report, and drop any subsequent events during the backoff period with the [`ratelimit_backoff`](/sdk/telemetry/client-reports/#discard-reasons) discard reason. SDKs **MAY** retry sending the envelope when a network error occurs, such as: * Connection timeout * DSN resolution failure From 7a4f521846bcfbf825e11108b711ee2e28e81144 Mon Sep 17 00:00:00 2001 From: Philipp Hofmann Date: Thu, 20 Nov 2025 09:34:01 +0100 Subject: [PATCH 4/4] fix wording --- 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 28e4e0e892169..1df0b5c7db6e4 100644 --- a/develop-docs/sdk/expected-features/index.mdx +++ b/develop-docs/sdk/expected-features/index.mdx @@ -251,7 +251,7 @@ 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** apply the [rate limiting](/sdk/expected-features/rate-limiting/) rules, discard the envelope without recording a client report, and drop any subsequent events during the backoff period with the [`ratelimit_backoff`](/sdk/telemetry/client-reports/#discard-reasons) discard reason. 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` (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: * Connection timeout * DSN resolution failure