codes.go (9104B)
1 /* 2 * 3 * Copyright 2014 gRPC authors. 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 * 17 */ 18 19 // Package codes defines the canonical error codes used by gRPC. It is 20 // consistent across various languages. 21 package codes // import "google.golang.org/grpc/codes" 22 23 import ( 24 "fmt" 25 "strconv" 26 ) 27 28 // A Code is an unsigned 32-bit error code as defined in the gRPC spec. 29 type Code uint32 30 31 const ( 32 // OK is returned on success. 33 OK Code = 0 34 35 // Canceled indicates the operation was canceled (typically by the caller). 36 // 37 // The gRPC framework will generate this error code when cancellation 38 // is requested. 39 Canceled Code = 1 40 41 // Unknown error. An example of where this error may be returned is 42 // if a Status value received from another address space belongs to 43 // an error-space that is not known in this address space. Also 44 // errors raised by APIs that do not return enough error information 45 // may be converted to this error. 46 // 47 // The gRPC framework will generate this error code in the above two 48 // mentioned cases. 49 Unknown Code = 2 50 51 // InvalidArgument indicates client specified an invalid argument. 52 // Note that this differs from FailedPrecondition. It indicates arguments 53 // that are problematic regardless of the state of the system 54 // (e.g., a malformed file name). 55 // 56 // This error code will not be generated by the gRPC framework. 57 InvalidArgument Code = 3 58 59 // DeadlineExceeded means operation expired before completion. 60 // For operations that change the state of the system, this error may be 61 // returned even if the operation has completed successfully. For 62 // example, a successful response from a server could have been delayed 63 // long enough for the deadline to expire. 64 // 65 // The gRPC framework will generate this error code when the deadline is 66 // exceeded. 67 DeadlineExceeded Code = 4 68 69 // NotFound means some requested entity (e.g., file or directory) was 70 // not found. 71 // 72 // This error code will not be generated by the gRPC framework. 73 NotFound Code = 5 74 75 // AlreadyExists means an attempt to create an entity failed because one 76 // already exists. 77 // 78 // This error code will not be generated by the gRPC framework. 79 AlreadyExists Code = 6 80 81 // PermissionDenied indicates the caller does not have permission to 82 // execute the specified operation. It must not be used for rejections 83 // caused by exhausting some resource (use ResourceExhausted 84 // instead for those errors). It must not be 85 // used if the caller cannot be identified (use Unauthenticated 86 // instead for those errors). 87 // 88 // This error code will not be generated by the gRPC core framework, 89 // but expect authentication middleware to use it. 90 PermissionDenied Code = 7 91 92 // ResourceExhausted indicates some resource has been exhausted, perhaps 93 // a per-user quota, or perhaps the entire file system is out of space. 94 // 95 // This error code will be generated by the gRPC framework in 96 // out-of-memory and server overload situations, or when a message is 97 // larger than the configured maximum size. 98 ResourceExhausted Code = 8 99 100 // FailedPrecondition indicates operation was rejected because the 101 // system is not in a state required for the operation's execution. 102 // For example, directory to be deleted may be non-empty, an rmdir 103 // operation is applied to a non-directory, etc. 104 // 105 // A litmus test that may help a service implementor in deciding 106 // between FailedPrecondition, Aborted, and Unavailable: 107 // (a) Use Unavailable if the client can retry just the failing call. 108 // (b) Use Aborted if the client should retry at a higher-level 109 // (e.g., restarting a read-modify-write sequence). 110 // (c) Use FailedPrecondition if the client should not retry until 111 // the system state has been explicitly fixed. E.g., if an "rmdir" 112 // fails because the directory is non-empty, FailedPrecondition 113 // should be returned since the client should not retry unless 114 // they have first fixed up the directory by deleting files from it. 115 // (d) Use FailedPrecondition if the client performs conditional 116 // REST Get/Update/Delete on a resource and the resource on the 117 // server does not match the condition. E.g., conflicting 118 // read-modify-write on the same resource. 119 // 120 // This error code will not be generated by the gRPC framework. 121 FailedPrecondition Code = 9 122 123 // Aborted indicates the operation was aborted, typically due to a 124 // concurrency issue like sequencer check failures, transaction aborts, 125 // etc. 126 // 127 // See litmus test above for deciding between FailedPrecondition, 128 // Aborted, and Unavailable. 129 // 130 // This error code will not be generated by the gRPC framework. 131 Aborted Code = 10 132 133 // OutOfRange means operation was attempted past the valid range. 134 // E.g., seeking or reading past end of file. 135 // 136 // Unlike InvalidArgument, this error indicates a problem that may 137 // be fixed if the system state changes. For example, a 32-bit file 138 // system will generate InvalidArgument if asked to read at an 139 // offset that is not in the range [0,2^32-1], but it will generate 140 // OutOfRange if asked to read from an offset past the current 141 // file size. 142 // 143 // There is a fair bit of overlap between FailedPrecondition and 144 // OutOfRange. We recommend using OutOfRange (the more specific 145 // error) when it applies so that callers who are iterating through 146 // a space can easily look for an OutOfRange error to detect when 147 // they are done. 148 // 149 // This error code will not be generated by the gRPC framework. 150 OutOfRange Code = 11 151 152 // Unimplemented indicates operation is not implemented or not 153 // supported/enabled in this service. 154 // 155 // This error code will be generated by the gRPC framework. Most 156 // commonly, you will see this error code when a method implementation 157 // is missing on the server. It can also be generated for unknown 158 // compression algorithms or a disagreement as to whether an RPC should 159 // be streaming. 160 Unimplemented Code = 12 161 162 // Internal errors. Means some invariants expected by underlying 163 // system has been broken. If you see one of these errors, 164 // something is very broken. 165 // 166 // This error code will be generated by the gRPC framework in several 167 // internal error conditions. 168 Internal Code = 13 169 170 // Unavailable indicates the service is currently unavailable. 171 // This is a most likely a transient condition and may be corrected 172 // by retrying with a backoff. Note that it is not always safe to retry 173 // non-idempotent operations. 174 // 175 // See litmus test above for deciding between FailedPrecondition, 176 // Aborted, and Unavailable. 177 // 178 // This error code will be generated by the gRPC framework during 179 // abrupt shutdown of a server process or network connection. 180 Unavailable Code = 14 181 182 // DataLoss indicates unrecoverable data loss or corruption. 183 // 184 // This error code will not be generated by the gRPC framework. 185 DataLoss Code = 15 186 187 // Unauthenticated indicates the request does not have valid 188 // authentication credentials for the operation. 189 // 190 // The gRPC framework will generate this error code when the 191 // authentication metadata is invalid or a Credentials callback fails, 192 // but also expect authentication middleware to generate it. 193 Unauthenticated Code = 16 194 195 _maxCode = 17 196 ) 197 198 var strToCode = map[string]Code{ 199 `"OK"`: OK, 200 `"CANCELLED"`:/* [sic] */ Canceled, 201 `"UNKNOWN"`: Unknown, 202 `"INVALID_ARGUMENT"`: InvalidArgument, 203 `"DEADLINE_EXCEEDED"`: DeadlineExceeded, 204 `"NOT_FOUND"`: NotFound, 205 `"ALREADY_EXISTS"`: AlreadyExists, 206 `"PERMISSION_DENIED"`: PermissionDenied, 207 `"RESOURCE_EXHAUSTED"`: ResourceExhausted, 208 `"FAILED_PRECONDITION"`: FailedPrecondition, 209 `"ABORTED"`: Aborted, 210 `"OUT_OF_RANGE"`: OutOfRange, 211 `"UNIMPLEMENTED"`: Unimplemented, 212 `"INTERNAL"`: Internal, 213 `"UNAVAILABLE"`: Unavailable, 214 `"DATA_LOSS"`: DataLoss, 215 `"UNAUTHENTICATED"`: Unauthenticated, 216 } 217 218 // UnmarshalJSON unmarshals b into the Code. 219 func (c *Code) UnmarshalJSON(b []byte) error { 220 // From json.Unmarshaler: By convention, to approximate the behavior of 221 // Unmarshal itself, Unmarshalers implement UnmarshalJSON([]byte("null")) as 222 // a no-op. 223 if string(b) == "null" { 224 return nil 225 } 226 if c == nil { 227 return fmt.Errorf("nil receiver passed to UnmarshalJSON") 228 } 229 230 if ci, err := strconv.ParseUint(string(b), 10, 32); err == nil { 231 if ci >= _maxCode { 232 return fmt.Errorf("invalid code: %q", ci) 233 } 234 235 *c = Code(ci) 236 return nil 237 } 238 239 if jc, ok := strToCode[string(b)]; ok { 240 *c = jc 241 return nil 242 } 243 return fmt.Errorf("invalid code: %q", string(b)) 244 }