Clarify OAuth endpoints response and improve "Other Status Codes" sections

Bug Reports Documentation Issues
,
#1

Currently as a developer it’s too hard to properly handle errors in my application when interacting with the Open Cloud API as documentation is too unclear and vague.

First thing first OAuth2 endpoints completely lack error responses listings. How am I supposed to guess every error they may return in my code? Some programming languages like C# provide a way to differentiate error handling in try/catch blocks by exception type.

For example I would be able to throw more descriptive exceptions if I knew what errors endpoints return.

try
{
    res.EnsureSuccessfulStatusCode();
}
catch (InvalidGrantException)
{
    // ...
}
catch (InvalidAccessTokenException)
{
    // ...
}

The above code snippet would be possible if all errors were documented.

As for other Open Cloud endpoints the situation isn’t as bad as most (not all) of them list error HTTP status codes, but they still don’t tell us what could’ve caused the error.

As I said not all endpoint docs report “Other Status Codes” for example most of V1’s Data Stores don’t.

To sum it up: it would be really useful as a developer to know what errors to expect from Open Cloud APIs so that I can appropriately manage each one of them. I understand refusing to do that for internal APIs but as Open Cloud - like staff said in multiple occasions - is the only APIs collection intended for developers’ use it should really be done as that would greately improve developers’ experience.

Page URL: https://create.roblox.com/docs/cloud/reference

#2

I’ll take a look if we need to make this more clear in the docs, but just for information, OAuth 2.0 is a specification by the IETF and you can find the spec here: RFC 6749 - The OAuth 2.0 Authorization Framework

We are fully compliant with the spec, please post bug reports if you see otherwise.

We also support: RFC 7636 - Proof Key for Code Exchange by OAuth Public Clients

2 Likes
#3

Thanks it might be worth reporting the RFC on the docs. While this is a good solution for OAuth, the problem still stands with other endpoints.

1 Like
#4

Hi @NinjaFurfante07! Trying to understand the ask with regard to the other Open Cloud endpoints a bit better - As you mentioned, we currently document the error responses for both V1 and V2 resources on the Errors page in Cloud / Reference page. The error response typically includes a high-level error/code along with a more detailed message/error type.

Are you looking for these more detailed messages/error types to be documented? For example, in the case of the V1 Standard Data Stores endpoints, the possible values of errorDetails field.

2 Likes
#5

Yes that’s exactly what I’m asking! The reason is that would allow us to do something like this:

public static async Task HandleOAuthError(HttpResponseMessage res, HttpRequestException ex)
{
    RobloxOAuthErrorException oauthEx = await res.Content.ReadFromJsonAsync<RobloxOAuthErrorException>() ??
        throw new Exception("Could not parse JSON");

    throw oauthEx.Error switch
    {
        "invalid_request" => new OAuthInvalidRequestException(oauthEx.Description),
        "invalid_client" => new OAuthInvalidClientException(oauthEx.Description),
        "invalid_grant" => new OAuthInvalidGrantException(oauthEx.Description),
        "unauthorized_client" => new OAuthUnauthorizedClientException(oauthEx.Description),
        "unsupported_grant_type" => new OAuthUnsupportedGrantTypeException(oauthEx.Description),
        "invalid_scope" => new OAuthInvalidScopeException(oauthEx.Description),
        _ => oauthEx,
    };
}

(The snippet is for OAuth since RFC 6749 documents all possible errors but errors would be documented like the RFC does).

Knowing every error the API could return would greatly help in managing them appropriately and adopt a different behavior for a better UX.

2 Likes
#6

Actually there are some endpoints like /oauth/v1/token/resources and /oauth/v1/userinfo which return an errors that are not part of RFC 6749.

For example when an invalid access token is supplied:

{"error":"invalid_token","error_description":"Token is invalid"}
2 Likes
#7

Got it, so in this case, we follow the RFC 6750 - The OAuth 2.0 Authorization Framework: Bearer Token Usage spec for those endpoints (see in particular this section). It defines the invalid_token error. The /oauth/v1/userinfo is the OpenID Connect UserInfo endpoint, defined here, which refers to the RFC 6750.

Now on closer inspection, I do realize we may have made a small error here in that we return that error as a response body instead of as a response header (the spec mandates it as putting it in the WWW-Authenticate header), so that’s a bit weird. We’ll probably fix these endpoints to have the same error in the response header as well.

Are there any other cases than that one that you’re concerned about?

1 Like
#8

No other use case, I’m just concerned about handling all kind of errors differently and knowing what to expect in case of an error. Most importantly non RFC OAuth2 endpoints (datastores, etc.).

#9

Sounds good, we can definitely see where we can add more out-links to the RFCs, and probably we should integrate some of the content onto our own documentation since the RFCs are quite opiniated on how they lay out the content (very technical, no formatting).

It might take us some time to get around to this, but we’ll keep it in mind as we evolve the Open Cloud docs. Thanks for the feedback!

1 Like
#10

Really appreciate it. And just to make it extremely clear take V2 errors model provided in the errors section:

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

We are told that the code could be INVALID_ARGUMENT, but what is details object going to be? What can I expect from a datastore v2 error? Here a key indicating which argument in the request was invalid would be really useful.

Anyway I’m looking forward to the docs improvements!