Handling errors in the Yandex Cloud API
If an operation completes successfully, the server returns the OK status to the client. If an error occurs during the operation, the server returns a message with the error description.
Errors in APIs are described using the google.rpc.Status
The table below provides a list of errors generated by APIs.
The .proto specification is available in the repository on GitHub
Error message format
The Status
message contains three fields:
Field | Description |
---|---|
code |
int32gRPC error code. Possible error codes are defined in google.rpc.Code |
message |
stringError description. |
details |
repeated google.protobuf.AnyError details. This field contains detailed information about the error, such as which parameters were specified incorrectly. Message types used in this field are defined in google.rpc.ErrorDetails |
Below is a gRPC description of the Status
message:
message Status {
// A gRPC code of the error. Acceptable values are defined
// in [google.rpc.Code].
int32 code = 1;
// Error description.
string message = 2;
// Detailed information about the error.
repeated google.protobuf.Any details = 3;
}
HTTP mapping
To see how gRPC statuses correspond to HTTP codes, see google.rpc.Code
The example below shows an error that can be returned by the server in response to a REST request:
{
"code": 16,
"message": "Token is invalid or has expired.",
"details": [
{
"@type": "type.googleapis.com/google.rpc.RequestInfo",
"requestId": "e38e71c3-adc6-4584-98a4-b0f103d55f61"
}
]
}
List of possible errors
gRPC code | gRPC status | HTTP code | Error description |
---|---|---|---|
1 | CANCELLED | 499 | The operation was aborted on the client side. |
2 | UNKNOWN | 500 | Unknown error. |
3 | INVALID_ARGUMENT | 400 | Incorrect request parameters specified. Details are provided in the details field. |
4 | DEADLINE_EXCEEDED | 504 | The server response timed out. |
5 | NOT_FOUND | 404 | The requested resource not found. |
6 | ALREADY_EXISTS | 409 | Attempt to create a resource that already exists. |
7 | PERMISSION_DENIED | 403 | The user has no permissions required to perform the operation. |
8 | RESOURCE_EXHAUSTED | 429 | The request limit exceeded. |
9 | FAILED_PRECONDITION | 400 | The operation was canceled as its preconditions were not met. Examples: an attempt to delete a non-empty folder or to run the rmdir command for an object that is not a folder. |
10 | ABORTED | 409 | The operation failed due to a concurrent computing conflict, such as an invalid sequence of commands or an aborted transaction. |
11 | OUT_OF_RANGE | 400 | Out of range. For example, searching or reading outside of the file. |
12 | NOT_IMPLEMENTED | 501 | The operation is not supported by the service. |
13 | INTERNAL | 500 | Internal server error. This error means that the operation cannot be performed due to a server-side technical problem. For example, due to insufficient computing resources. |
14 | UNAVAILABLE | 503 | The service is currently unavailable. Try again in a few seconds. |
15 | DATA_LOSS | 500 | Permanent data loss or damage. |
16 | UNAUTHENTICATED | 401 | The operation requires authentication. |
Handling asynchronous errors
When asynchronous operations are called, the server returns the Operation object. If an error occurs, the Status
message is added to the Operation
object in the error
field.