feat docs: update 'network-error' corresponding details

commit_hash:6c720f78deb0360bd2ea4067a3c64d493b979152

Author: kpavlov00

grpc/include/userver/ugrpc/client/completion_status.hpp

@@ -25,12 +25,19 @@ namespace ugrpc::client {
 /// @see @ref CompletionStatus
 enum class SpecialCaseCompletionType : std::uint8_t {
     /// [special_cases_declaration]
-    /// @brief Network-level error occurred before receiving a gRPC status.
+    /// @brief The RPC was interrupted at the network/transport level without a gRPC status.
     ///
-    /// Indicates that the underlying network operation failed (e.g., connection lost,
-    /// socket error) before the server could send a proper gRPC status response.
-    /// This means that the underlying grpcpp framework returned an error.
-    /// This is distinct from `grpc::StatusCode::UNAVAILABLE` which is a valid gRPC status.
+    /// The call did not finish with a gRPC status from the server: the connection was lost, reset
+    /// or otherwise interrupted. This is distinct from `grpc::StatusCode::UNAVAILABLE`, which is a
+    /// valid gRPC status.
+    ///
+    /// For a unary call this is reported only when no concrete gRPC status is available and the
+    /// response could not be obtained (not received, or received but not parseable). Whenever a
+    /// concrete status is available instead (for example `UNAVAILABLE` or `CANCELLED`), it is
+    /// reported as that `grpc::Status` rather than as this special case.
+    ///
+    /// Surfaces to the caller as @ref ugrpc::client::RpcInterruptedError; for unary calls it is
+    /// retryable.
     kNetworkError,
     /// @brief Request timed out with deadline propagation enabled.
     ///

grpc/include/userver/ugrpc/client/exceptions.hpp

@@ -34,8 +34,10 @@ class RpcError : public BaseError {
     RpcError(std::string_view call_name, std::string_view additional_info);
 };
 
-/// @brief RPC failed without a status. This means that either the call got
-/// cancelled using `TryCancel` or the channel is broken.
+/// @brief RPC failed without a gRPC status because it was interrupted at the transport level
+/// (cancelled via `TryCancel`, or the connection was lost/reset). For a unary call it is thrown
+/// only when no concrete gRPC status is available; when a status is available it is instead
+/// surfaced as the corresponding @ref ugrpc::client::ErrorWithStatus. Retryable.
 /// Note: Deadline expiration throws  @ref ugrpc::client::DeadlineExceededError
 class RpcInterruptedError final : public RpcError {
 public:

scripts/docs/en/userver/grpc/grpc.md

@@ -429,7 +429,10 @@ These are the metrics provided for each gRPC method:
    * `network-error` — other RPCs that finished abruptly without a status,
      see ugrpc::client::RpcInterruptedError and
      ugrpc::server::RpcInterruptedError.
-     Such a unary network error is retryable, see
+     Client-side, a unary call is counted here only when it was interrupted at the
+     transport level and no concrete gRPC status is available; when a status is
+     available (for example `UNAVAILABLE` or `CANCELLED`), it is reported under that
+     status instead. Such a unary network error is retryable, see
      @ref scripts/docs/en/userver/grpc/timeouts_retries.md.
 * `abandoned-error` — RPCs that we forgot to `Finish`
   A client code drops an RPC object and don't wait of a response from a server OR is a bug in `ugrpc` usage.

scripts/docs/en/userver/grpc/timeouts_retries.md

@@ -49,12 +49,11 @@ Conditions for a retry to occur:
 3. The overall Deadline (including from @ref scripts/docs/en/userver/deadline_propagation.md) has not been exceeded;
 4. The @ref ugrpc::client::RetryLimiter "retry limiter" (if configured) allows the retry.
 
-@note In addition to the retryable status codes above, a unary network error
+@note A unary call interrupted at the transport level is retried like any other error: when a
+concrete gRPC status is available (for example `UNAVAILABLE` or `CANCELLED`) it is retried by that
+status code; otherwise it is reported as a network error
 (@ref ugrpc::client::SpecialCaseCompletionType "kNetworkError", surfaced as
-ugrpc::client::RpcInterruptedError) is also retryable. This includes the case when the completion
-queue reports `ok=false` on `Finish`, e.g. a response that was received but could not be
-deserialized. Note that grpc-core does not retry the latter on its own, because it had already
-observed a successful status on the wire; it is the userver retry loop that retries it.
+ugrpc::client::RpcInterruptedError), which is also retryable.
 
 ### Configuring Retries