Open Cloud Error Handling

To handle error responses properly, you need to understand the error model shared by all Open Cloud endpoints.

Error Model

All error responses have the same format, which includes:

  • An error field, which is a high-level cause that is applicable to all Open Cloud endpoints.
  • An explanatory error message, which further explains the error.
  • An errorDetails object, which covers more information of the error that is specific to each API.

To analyze the root cause of an error, refer to the value of the error field and the errorDetails field. Use the message field as a supplementary for error handling, as sometimes it might not cover the same level of details as the errorDetails field.

Example Error Response

{
"error": "INVALID_ARGUMENT",
"message": "Invalid cursor.",
"errorDetails": [
{
"errorDetailType": "DatastoreErrorInfo",
"datastoreErrorCode": "InvalidCursor"
}
]
}

The example error response shows the high-level Open Cloud error as INVALID_ARGUMENT, the error message as InvalidCursor, and the errorDetails specific to data stores with the datastoreErrorCode as InvalidCursor. From the error and datastoreErrorCode fields of the response, you can understand that you passed an invalid cursor parameter that caused the error. You can then correct your cursor parameter to resolve the issue.

Error Codes

Reference the following table for a summary of all high-level Open Cloud errors.

HTTP Status Code Error Descriptions
400 INVALID_ARGUMENT You passed an invalid argument, such as an invalid universeId.
403 INSUFFICIENT_SCOPE The request requires higher privileges than provided by the access token.
403 PERMISSION_DENIED Your request doesn't have sufficient scope to perform the operation.
404 NOT_FOUND The system can't find your specified resources, such as a data store.
409 ABORTED The operation was aborted due to a conflict, such as publishing a place that is not part of the universe.
429 RESOURCE_EXHAUSTED You don't have enough quota to perform the operation, typically due to sending too many requests.
499 CANCELLED The system terminates the request, typically due to a client side timeout.
500 INTERNAL Internal server error. Typically a server bug.
501 NOT_IMPLEMENTED The server doesn't implement the API method.
503 UNAVAILABLE Service unavailable. Typically the server is down.