Handling errors

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

The error-list provides a list of errors currently generated by APIs.

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 {
  // gRPC error code. Possible values are defined
  // in [google.rpc.Code].
  int32 code = 1;

  // Error description.
  string message = 2;

  // Error details.
  repeated google.protobuf.Any details = 3;
}

HTTP mapping

Mapping of gRPC statuses to HTTP codes is described in google.rpc.Code.

The example below shows an error that can be returned by the server in response to a REST request:

 {
   "error": {
     "code": "499",
     "message": "The operation was cancelled, typically by the caller.",
     "status": "CANCELLED",
     "details": [{
       "@type": "type.googleapis.com/google.rpc.RetryInfo",
       ...
     }]
   }
 }

List of possible errors

HTTP gRPC Error description
400 INVALID_ARGUMENT Incorrect request parameters specified. Details are provided in the details field.
401 UNAUTHENTICATED The operation requires authentication.
403 PERMISSION_DENIED The user has no permissions required to perform the operation.
404 NOT_FOUND The requested resource not found.
409 ALREADY_EXISTS Attempt to create a resource that already exists.
429 RESOURCE_EXHAUSTED The request limit exceeded.
499 CANCELLED The operation was aborted on the client side.
500 UNKNOWN Unknown error.
500 INTERNAL 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.
501 NOT_IMPLEMENTED The operation is not supported by the service.
503 UNAVAILABLE The service is currently unavailable. Try again in a few seconds.

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.