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.
21package codes // import "google.golang.org/grpc/codes"
22
23import (
24	"fmt"
25	"strconv"
26)
27
28// A Code is an unsigned 32-bit error code as defined in the gRPC spec.
29type Code uint32
30
31const (
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
38	// Unknown error. An example of where this error may be returned is
39	// if a Status value received from another address space belongs to
40	// an error-space that is not known in this address space. Also
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
69	// instead for those errors). It must not be
70	// used if the caller cannot be identified (use Unauthenticated
71	// instead for those errors).
72	PermissionDenied Code = 7
73
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
89	//      the system state has been explicitly fixed. E.g., if an "rmdir"
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
118	// OutOfRange. We recommend using OutOfRange (the more specific
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
128	// Internal errors. Means some invariants expected by underlying
129	// system has been broken. If you see one of these errors,
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. Note that it is not always safe to retry
136	// non-idempotent operations.
137	//
138	// See litmus test above for deciding between FailedPrecondition,
139	// Aborted, and Unavailable.
140	Unavailable Code = 14
141
142	// DataLoss indicates unrecoverable data loss or corruption.
143	DataLoss Code = 15
144
145	// Unauthenticated indicates the request does not have valid
146	// authentication credentials for the operation.
147	Unauthenticated Code = 16
148
149	_maxCode = 17
150)
151
152var strToCode = map[string]Code{
153	`"OK"`: OK,
154	`"CANCELLED"`:/* [sic] */ Canceled,
155	`"UNKNOWN"`:             Unknown,
156	`"INVALID_ARGUMENT"`:    InvalidArgument,
157	`"DEADLINE_EXCEEDED"`:   DeadlineExceeded,
158	`"NOT_FOUND"`:           NotFound,
159	`"ALREADY_EXISTS"`:      AlreadyExists,
160	`"PERMISSION_DENIED"`:   PermissionDenied,
161	`"RESOURCE_EXHAUSTED"`:  ResourceExhausted,
162	`"FAILED_PRECONDITION"`: FailedPrecondition,
163	`"ABORTED"`:             Aborted,
164	`"OUT_OF_RANGE"`:        OutOfRange,
165	`"UNIMPLEMENTED"`:       Unimplemented,
166	`"INTERNAL"`:            Internal,
167	`"UNAVAILABLE"`:         Unavailable,
168	`"DATA_LOSS"`:           DataLoss,
169	`"UNAUTHENTICATED"`:     Unauthenticated,
170}
171
172// UnmarshalJSON unmarshals b into the Code.
173func (c *Code) UnmarshalJSON(b []byte) error {
174	// From json.Unmarshaler: By convention, to approximate the behavior of
175	// Unmarshal itself, Unmarshalers implement UnmarshalJSON([]byte("null")) as
176	// a no-op.
177	if string(b) == "null" {
178		return nil
179	}
180	if c == nil {
181		return fmt.Errorf("nil receiver passed to UnmarshalJSON")
182	}
183
184	if ci, err := strconv.ParseUint(string(b), 10, 32); err == nil {
185		if ci >= _maxCode {
186			return fmt.Errorf("invalid code: %q", ci)
187		}
188
189		*c = Code(ci)
190		return nil
191	}
192
193	if jc, ok := strToCode[string(b)]; ok {
194		*c = jc
195		return nil
196	}
197	return fmt.Errorf("invalid code: %q", string(b))
198}
199