Contact UsGet started

Handling errors in the Yandex Cloud API

Written by
Updated at April 23, 2025

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. This error model is used in both gRPC and REST interfaces.

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 int32
gRPC error code. Possible error codes are defined in google.rpc.Code.
message string
Error description.
details repeated google.protobuf.Any
Error 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.

Previous
Pagination
Next
Overview