]>
Commit | Line | Data |
---|---|---|
15c0b25d AP |
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 | ||
107c1cdb ND |
23 | import ( |
24 | "fmt" | |
25 | "strconv" | |
26 | ) | |
27 | ||
15c0b25d AP |
28 | // A Code is an unsigned 32-bit error code as defined in the gRPC spec. |
29 | type Code uint32 | |
30 | ||
15c0b25d AP |
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 | Canceled Code = 1 | |
37 | ||
107c1cdb | 38 | // Unknown error. An example of where this error may be returned is |
15c0b25d | 39 | // if a Status value received from another address space belongs to |
107c1cdb | 40 | // an error-space that is not known in this address space. Also |
15c0b25d AP |
41 | // errors raised by APIs that do not return enough error information |
42 | // may be converted to this error. | |
43 | Unknown Code = 2 | |
44 | ||
45 | // InvalidArgument indicates client specified an invalid argument. | |
46 | // Note that this differs from FailedPrecondition. It indicates arguments | |
47 | // that are problematic regardless of the state of the system | |
48 | // (e.g., a malformed file name). | |
49 | InvalidArgument Code = 3 | |
50 | ||
51 | // DeadlineExceeded means operation expired before completion. | |
52 | // For operations that change the state of the system, this error may be | |
53 | // returned even if the operation has completed successfully. For | |
54 | // example, a successful response from a server could have been delayed | |
55 | // long enough for the deadline to expire. | |
56 | DeadlineExceeded Code = 4 | |
57 | ||
58 | // NotFound means some requested entity (e.g., file or directory) was | |
59 | // not found. | |
60 | NotFound Code = 5 | |
61 | ||
62 | // AlreadyExists means an attempt to create an entity failed because one | |
63 | // already exists. | |
64 | AlreadyExists Code = 6 | |
65 | ||
66 | // PermissionDenied indicates the caller does not have permission to | |
67 | // execute the specified operation. It must not be used for rejections | |
68 | // caused by exhausting some resource (use ResourceExhausted | |
107c1cdb | 69 | // instead for those errors). It must not be |
15c0b25d AP |
70 | // used if the caller cannot be identified (use Unauthenticated |
71 | // instead for those errors). | |
72 | PermissionDenied Code = 7 | |
73 | ||
15c0b25d AP |
74 | // ResourceExhausted indicates some resource has been exhausted, perhaps |
75 | // a per-user quota, or perhaps the entire file system is out of space. | |
76 | ResourceExhausted Code = 8 | |
77 | ||
78 | // FailedPrecondition indicates operation was rejected because the | |
79 | // system is not in a state required for the operation's execution. | |
80 | // For example, directory to be deleted may be non-empty, an rmdir | |
81 | // operation is applied to a non-directory, etc. | |
82 | // | |
83 | // A litmus test that may help a service implementor in deciding | |
84 | // between FailedPrecondition, Aborted, and Unavailable: | |
85 | // (a) Use Unavailable if the client can retry just the failing call. | |
86 | // (b) Use Aborted if the client should retry at a higher-level | |
87 | // (e.g., restarting a read-modify-write sequence). | |
88 | // (c) Use FailedPrecondition if the client should not retry until | |
107c1cdb | 89 | // the system state has been explicitly fixed. E.g., if an "rmdir" |
15c0b25d AP |
90 | // fails because the directory is non-empty, FailedPrecondition |
91 | // should be returned since the client should not retry unless | |
92 | // they have first fixed up the directory by deleting files from it. | |
93 | // (d) Use FailedPrecondition if the client performs conditional | |
94 | // REST Get/Update/Delete on a resource and the resource on the | |
95 | // server does not match the condition. E.g., conflicting | |
96 | // read-modify-write on the same resource. | |
97 | FailedPrecondition Code = 9 | |
98 | ||
99 | // Aborted indicates the operation was aborted, typically due to a | |
100 | // concurrency issue like sequencer check failures, transaction aborts, | |
101 | // etc. | |
102 | // | |
103 | // See litmus test above for deciding between FailedPrecondition, | |
104 | // Aborted, and Unavailable. | |
105 | Aborted Code = 10 | |
106 | ||
107 | // OutOfRange means operation was attempted past the valid range. | |
108 | // E.g., seeking or reading past end of file. | |
109 | // | |
110 | // Unlike InvalidArgument, this error indicates a problem that may | |
111 | // be fixed if the system state changes. For example, a 32-bit file | |
112 | // system will generate InvalidArgument if asked to read at an | |
113 | // offset that is not in the range [0,2^32-1], but it will generate | |
114 | // OutOfRange if asked to read from an offset past the current | |
115 | // file size. | |
116 | // | |
117 | // There is a fair bit of overlap between FailedPrecondition and | |
107c1cdb | 118 | // OutOfRange. We recommend using OutOfRange (the more specific |
15c0b25d AP |
119 | // error) when it applies so that callers who are iterating through |
120 | // a space can easily look for an OutOfRange error to detect when | |
121 | // they are done. | |
122 | OutOfRange Code = 11 | |
123 | ||
124 | // Unimplemented indicates operation is not implemented or not | |
125 | // supported/enabled in this service. | |
126 | Unimplemented Code = 12 | |
127 | ||
107c1cdb ND |
128 | // Internal errors. Means some invariants expected by underlying |
129 | // system has been broken. If you see one of these errors, | |
15c0b25d AP |
130 | // something is very broken. |
131 | Internal Code = 13 | |
132 | ||
133 | // Unavailable indicates the service is currently unavailable. | |
134 | // This is a most likely a transient condition and may be corrected | |
135 | // by retrying with a backoff. | |
136 | // | |
137 | // See litmus test above for deciding between FailedPrecondition, | |
138 | // Aborted, and Unavailable. | |
139 | Unavailable Code = 14 | |
140 | ||
141 | // DataLoss indicates unrecoverable data loss or corruption. | |
142 | DataLoss Code = 15 | |
107c1cdb ND |
143 | |
144 | // Unauthenticated indicates the request does not have valid | |
145 | // authentication credentials for the operation. | |
146 | Unauthenticated Code = 16 | |
147 | ||
148 | _maxCode = 17 | |
15c0b25d | 149 | ) |
107c1cdb ND |
150 | |
151 | var strToCode = map[string]Code{ | |
152 | `"OK"`: OK, | |
153 | `"CANCELLED"`:/* [sic] */ Canceled, | |
154 | `"UNKNOWN"`: Unknown, | |
155 | `"INVALID_ARGUMENT"`: InvalidArgument, | |
156 | `"DEADLINE_EXCEEDED"`: DeadlineExceeded, | |
157 | `"NOT_FOUND"`: NotFound, | |
158 | `"ALREADY_EXISTS"`: AlreadyExists, | |
159 | `"PERMISSION_DENIED"`: PermissionDenied, | |
160 | `"RESOURCE_EXHAUSTED"`: ResourceExhausted, | |
161 | `"FAILED_PRECONDITION"`: FailedPrecondition, | |
162 | `"ABORTED"`: Aborted, | |
163 | `"OUT_OF_RANGE"`: OutOfRange, | |
164 | `"UNIMPLEMENTED"`: Unimplemented, | |
165 | `"INTERNAL"`: Internal, | |
166 | `"UNAVAILABLE"`: Unavailable, | |
167 | `"DATA_LOSS"`: DataLoss, | |
168 | `"UNAUTHENTICATED"`: Unauthenticated, | |
169 | } | |
170 | ||
171 | // UnmarshalJSON unmarshals b into the Code. | |
172 | func (c *Code) UnmarshalJSON(b []byte) error { | |
173 | // From json.Unmarshaler: By convention, to approximate the behavior of | |
174 | // Unmarshal itself, Unmarshalers implement UnmarshalJSON([]byte("null")) as | |
175 | // a no-op. | |
176 | if string(b) == "null" { | |
177 | return nil | |
178 | } | |
179 | if c == nil { | |
180 | return fmt.Errorf("nil receiver passed to UnmarshalJSON") | |
181 | } | |
182 | ||
183 | if ci, err := strconv.ParseUint(string(b), 10, 32); err == nil { | |
184 | if ci >= _maxCode { | |
185 | return fmt.Errorf("invalid code: %q", ci) | |
186 | } | |
187 | ||
188 | *c = Code(ci) | |
189 | return nil | |
190 | } | |
191 | ||
192 | if jc, ok := strToCode[string(b)]; ok { | |
193 | *c = jc | |
194 | return nil | |
195 | } | |
196 | return fmt.Errorf("invalid code: %q", string(b)) | |
197 | } |