Open Cloud Data Types and Error Handling

To prevent and handle error responses properly when using Open Cloud Web APIs, make sure you pass the correct data types in your requests and understand the error model for finding the cause of an error.

Data Types

Open Cloud APIs use JSON to pass in data in the body and support the following data types:

String

The string data type is a sequence of characters, such a scope of a data store and a message for publishing to the server. Check the API reference before you pass a string value because some Open Cloud APIs do not support special symbols for strings. You must enclose string values in double quotes like the following example:

Example String

1{ "message": "Hello" }
2

Number

The number data type is an integer or floating point, such as a universeId and a placeId.

Example Number

1{ "universeId": 123456 }
2

Boolean

The boolean data type can have a value of either false or true.

Example Boolean

1{ "allScopes": true }
2

Object

The object data type is a set of key-value pairs. The keys must be strings, and the value can be simple data types such as strings, numbers, and booleans. Use curly braces to enclose an object and separate each key-value pair with a comma. Examples of objects in Open Cloud APIs include a DataStore and an Entrykey.

Example Object

1{
2 "DataStore": { "name": "DataStore1", "createdTime": "2022-01-01" }
3}
4

Array

The array data type is an ordered collection of elements such as strings, numbers, and objects. Enclose arrays with brackets and separate each value of an array with a comma.

Example Array

1{ "roblox-entry-userids": [123456, 234567, 345678] }
2

Error Model

All error responses returned by Open Cloud APIs have the same format, which includes:

  • An error as a high-level cause applicable to all Open Cloud API endpoints.
  • An explanatory error message to help you understand the error.
  • An errorDetails object on more information of the error that can be specific to each API.

To analyze the root cause of an error, don't rely on the error message. Instead, use the value of the error field and the errorDetails field for error handling, like the following example:


1{
2 "error": "INVALID_ARGUMENT",
3 "message": "Invalid cursor.",
4 "errorDetails": [
5 {
6 "errorDetailType": "DatastoreErrorInfo",
7 "datastoreErrorCode": "InvalidCursor"
8 }
9 ]
10}
11

The example error response shows the high-level Open Cloud error as INVALID_ARGUMENT, the error message as InvalidCursor, and errorDetails specific to DataStore API 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 Code

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.