Cloud

Errors

The following sections describe the error model for v2 and v1 resource methods, respectively.

v2 Resource Error Model

By default, resource methods respond with a 200 OK status. When requests are unsuccessful, Open Cloud returns standard error codes. All error responses have the same format, which include:

  • code - Represents the HTTP status code.
  • message - A message that explains the error.
  • details - An object that contains more information specific to the error.
Example Error

{
"code": "INVALID_ARGUMENT",
"message": "The provided filter is invalid.",
"details": [
{
...
}
]
}

Codes

The following table describes possible values for code.

CodeHTTP StatusDescription
INVALID_ARGUMENT400You passed an invalid argument, such as an invalid universeId. You might also have missing or invalid headers, such as Content-Length and Content-Type.
PERMISSION_DENIED403Your request doesn't have sufficient permissions or scopes to perform the operation.
NOT_FOUND404The system can't find your specified resources, such as a data store entry.
ABORTED409The operation was aborted.
RESOURCE_EXHAUSTED429You don't have enough quota to perform the operation, typically due to sending too many requests.
CANCELLED499The system terminates the request, typically due to a client side timeout.
INTERNAL500Internal server error, typically due to a server bug.
NOT_IMPLEMENTED501The server doesn't implement the API method.
UNAVAILABLE503Service is unavailable, typically returned when the server is down.

v1 Resource Error Model

All error responses have the same, standard 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 Standard DataStores 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.

All ordered data stores error responses have the same format, which includes:

Example Ordered DataStores Error Response

{
"code": "INVALID_ARGUMENT",
"message": "Invalid cursor."
}

The code will contain a string of the high-level error while the message will contain specific details related to the error

Codes

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

HTTP Status CodeErrorDescriptions
400INVALID_ARGUMENTYou passed an invalid argument, such as an invalid universeId. You might also have missing or invalid headers, such as Content-Length and Content-Type.
403INSUFFICIENT_SCOPEThe request requires higher privileges than provided by the access token.
403PERMISSION_DENIEDYour request doesn't have sufficient scope to perform the operation.
404NOT_FOUNDThe system can't find your specified resources, such as a data store.
409ABORTEDThe operation was aborted due to a conflict, such as publishing a place that is not part of the universe.
429RESOURCE_EXHAUSTEDYou don't have enough quota to perform the operation, typically due to sending too many requests.
499CANCELLEDThe system terminates the request, typically due to a client side timeout.
500INTERNALInternal server error. Typically a server bug.
501NOT_IMPLEMENTEDThe server doesn't implement the API method.
503UNAVAILABLEService unavailable. Typically the server is down.