[NBS] Document result codes

ydb-platform · Jan 10, 2025 · 5e5f534 · 5e5f534
1 parent 0f1b16c
commit 5e5f534
Show file tree

Hide file tree

Showing 2 changed files with 9 additions and 9 deletions.
diff --git a/cloud/storage/core/libs/common/error.h b/cloud/storage/core/libs/common/error.h
@@ -98,26 +98,26 @@ enum EFacilityCode
 enum EWellKnownResultCodes: ui32
 {
     S_OK                         = MAKE_SUCCESS(0),  // The request was completed successfully
-    S_FALSE                      = MAKE_SUCCESS(1),  // The request was not completed because the object does not exist; there is nothing to operate on
+    S_FALSE                      = MAKE_SUCCESS(1),  // The request was not completed because there is nothing to operate on
     S_ALREADY                    = MAKE_SUCCESS(2),
 
-    E_FAIL                       = MAKE_ERROR(0),
-    E_ARGUMENT                   = MAKE_ERROR(1),
-    E_REJECTED                   = MAKE_ERROR(2),
+    E_FAIL                       = MAKE_ERROR(0),  // Critical failure occured
+    E_ARGUMENT                   = MAKE_ERROR(1),  // Request arguments are ill-formed; no point in retrying
+    E_REJECTED                   = MAKE_ERROR(2),  // Request can be retried immediately (the most common code for retriable errors)
     // see MDB-11177#5fe20bc27e06002b58fe3eec
     // E_IO                      = MAKE_ERROR(3),
     E_INVALID_STATE              = MAKE_ERROR(4),  // The object is in an inappropriate state to perform the request
     E_TIMEOUT                    = MAKE_ERROR(5),  // The underlying layer failed to meet the deadline
-    E_NOT_FOUND                  = MAKE_ERROR(6),  // The object was not found
-    E_UNAUTHORIZED               = MAKE_ERROR(7),  // Authorization error
-    E_NOT_IMPLEMENTED            = MAKE_ERROR(8),  // The request is not implemented yet or should not be implemented at all
+    E_NOT_FOUND                  = MAKE_ERROR(6),
+    E_UNAUTHORIZED               = MAKE_ERROR(7),
+    E_NOT_IMPLEMENTED            = MAKE_ERROR(8),
     E_ABORTED                    = MAKE_ERROR(9),  // This request must not be retried; you should retry the higher-level request instead
     E_TRY_AGAIN                  = MAKE_ERROR(10),  // The control-plane request cannot be executed at this time; please try again later. Unlike E_REJECTED, which can be retried immediately
     E_IO                         = MAKE_ERROR(11),  // Input/output error. This is fatal, indicating it is impossible to read or write a block due to hardware failure
     E_CANCELLED                  = MAKE_ERROR(12),  // A legacy code for input/output errors. Unlike E_IO, it does not increment the fatal error counter in monitoring
     E_IO_SILENT                  = MAKE_ERROR(13),  // A legacy code for input/output errors. Unlike E_IO, it does not increment the fatal error counter in monitoring
     E_RETRY_TIMEOUT              = MAKE_ERROR(14),  // The total time limit (24 hours) for executing the request has expired
-    E_PRECONDITION_FAILED        = MAKE_ERROR(15),  // Preconditions within the object have been violated. This error is not retryable
+    E_PRECONDITION_FAILED        = MAKE_ERROR(15),  // Transition to the requested state would violate object's preconditions (e.g. unexpected order of operations, write request in read-only state...). This error is not retryable
 
     E_GRPC_CANCELLED             = MAKE_GRPC_ERROR(1),
     E_GRPC_UNKNOWN               = MAKE_GRPC_ERROR(2),

diff --git a/doc/blockstore/diagnostics/result-codes.md b/doc/blockstore/diagnostics/result-codes.md
@@ -28,4 +28,4 @@
 ## Error Flags
 
     EF_SILENT  // A flag that makes the target error EErrorKind::ErrorSilent. Such an error does not increment the fatal error counter. Caution: using this flag with a retryable error makes it non-retryable
-    EF_HW_PROBLEMS_DETECTED  // A flag indicating a problem with the NRD (Non Replicated Disk) or the Disk Agent
+    EF_HW_PROBLEMS_DETECTED  // A flag indicating a hardware problem