Child Item

Documentation: UploadError marked as “open union”, is “datatype with subtype”

In /upload, the documentation gives UploadError as an open union, but is actually a datatype with subtype.

Here is an example of what the server returns:

{
  "error_summary": "path/conflict/folder/...",                                                                                                                                      
  "error": {                                                                                                                                                                        
    ".tag": "path",                                                                                                                                                                 
    "reason": {                                                                                                                                                                     
      ".tag": "conflict",                                                                                                                                                           
      "conflict": {".tag": "folder"}                                                                                                                                                
    },                                                                                                                                                                              
    "upload_session_id": "AAAAAAAAVfvllHwbx7wZGA"                                                                                                                                   
  }                                                                                                                                                                                 
}

Find more posts tagged with

Developers

Comments

Greg-DB

Thanks for the note, and apologies for the confusion. You can find information on how errors are structured in the documentation here. In this case, this part is relevant:

Endpoint-specific errors (409)

The following table describes the top-level JSON object attributes present in the body of 409 responses.

Key Description
error A value that conforms to the error data type schema defined in the definition of each route.

So, for example, for /2/files/upload, the UploadError error type is referring to the value in the 'error' field, which can be either a 'path' or 'properties_error' (and is 'path' in your example here).

xguerin

Thank you Greg. I indeed agree with you about the content of the "error" field (being "path" in my example). However, IIRC, since the "UploadError" type is specified as an union, the ".tag" field is supposed to contain the name of the field in the union (as per the documentation). So I would have expected the following:

{
  "error_summary": "path/conflict/folder/...",                                                                                                                                      
  "error": {                                                                                                                                                                        
    ".tag": "path",                                                                                                                                                                 
    “path”: {
      "reason": {                                                                                                                                                                     
        ".tag": "conflict",                                                                                                                                                           
        "conflict": {".tag": "folder"}                                                                                                                                                
      },                                                                                                                                                                              
      "upload_session_id": "AAAAAAAAVfvllHwbx7wZGA"
    }                                                                                                                                   
  }                                                                                                                                                                                 
}

The fact that the content of "UploadWriteFailed" are merged with the content of "UploadError" makes me think of a subtype, not union.

Greg-DB

I see, thanks for clarifying. I believe the combined serialization is expected in this case, per the Stone documentation:

Union members that are ordinary structs (coord in the example) serialize as the struct with the addition of a .tag key.

In this case, the UploadError union member UploadWriteFailed is a struct.

R Brown

There are relatively few such cases in the API, and UploadWriteFailed (a struct inside an error union) is one of them; the others seem to be recent additions (e.g., LockConflictError inside LockFileError).

I also tripped over this error, because the author of the dropboxQt package that I use (https://github.com/osoftteam/dropboxQt) made the same mistake in their translation from Stone to C++/Qt (expecting the struct to stand as a single object embedded in the union, not broken out as fields). Sigh.