Problem
Open Cloud was meant to solve the issue of using internal undocumented APIs and provide a standardized API. However responses are not inline with the documentation and many objects are undocumented.
Open Cloud v1 errors
According to the docs (Errors | Documentation - Roblox Creator Hub)
Open Cloud v1 APIs share a standard format:
- 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.
There are already 2 issues in this portion of documentation:
- Error reponses return a
codefield contrary to what point 1 says - The errorDetails object is not documented and is not returned in most responses
The previously quoted docs are immediately followed by this
Here the docs talk about both
code and error, which one is correct? You only get the answer by trying it out and seeing that again code is correct.
Furthermore, the aforementioned errorDetails are not documented at all.
Gateway errors
There seems to be a validation layer in front of open cloud APIs, especially around authentication and URL validation.
By sending the following cURL request, the API will return a completely different error format, which is the same one used by legacy APIs.
curl -L -X GET 'https://apis.roblox.com/cloud/v2/users/8883805257/inventory-items?maxPageSize=10' \
-H "x-api-key: INVALID_KEY"
Response:
{"errors":[{"code":0,"message":"Invalid API Key"}]}
This response is nowhere near the documented ones. The same thing happens if you make the following cURL request:
curl -L -X GET 'https://apis.roblox.com/assets/v1/assets' \
-H "x-api-key: $KEY"
Yields the following because the resource is not found
{"errors":[{"code":0,"message":""}]}
Open Cloud v2 errors
Going back to the last example, 404 errors get better when the URL points to an inexisting resource on v2:
curl -L -X GET 'https://apis.roblox.com/cloud/v2/users/0'
-H "x-api-key: $KEY"
Yields the following response which follows the documented format:
{ "code": "NOT_FOUND", "message": "User not found." }
However 404 errors (and other errors caused by invalid requests) caused by an incorrect URL that doesn’t match any endpoint still return the legacy response:
curl -L -X GET 'https://apis.roblox.com/cloud/v2/users'
-H "x-api-key: $KEY"
Yields:
{"errors":[{"message":"","code":0}]}
Let’s compare two invalid URLs, both expect a number as the last path segment:
https://apis.roblox.com/cloud/v2/users/{ID_NUMBER}
https://apis.roblox.com/assets/v1/assets/{ID_NUMBER}
By sending a string instead of a number as resource ID, the APIs return different responses. V2 returns the documented format while v1 uses the legacy one.
{ "code": "INVALID_ARGUMENT", "message": "Invalid User ID in the request." }
{"errors":{"assetId":["The value 'a' is not valid."]},"type":"https://tools.ietf.org/html/rfc9110#section-15.5.1","title":"One or more validation errors occurred.","status":400,"extensions":{"traceId":"00-427917f0fc3b8375ee33e4603a7f0693-f3f6ad560ff1a122-00"}}
At this point we can say that v2 responses are much better, except not all v1 APIs are available on v2 (e.g assets).
Undocumented objects
The documentation mentions a lot of response objects that are never documented.
Let’s take Create Asset v1 as an example, this is the documented 200 response:
metadata, error and response are objects documented nowhere. How are we supposed to handle these without knowing their structure?
This goes for many other endpoints.
For example I was testing the Get Operation endpoint under the Assets API v1 and only at that point i found out what the response object looks like for it (which is just Asset).
Expected behavior
I expect API responses to be consistent with the documentation and the docs to be exhaustive.
While we can work around the inconsistent responses, being completely blind about returned objects is really frustrating and a major downside. The overall docs make up for a horrible developer experience, especially if you’re writing a wrapper.
