Question

After uploading a file with a name conflict with existing one, the server still responds with HTTP status code 201 Created. I had to parse the response body to know exactly whether it is really created or not. It sounds to me that I should be able to know the result of the operation just by the status code. So I am wondering if this is an intended behavior.

The following is the response I get

{
   "total_count":1,
   "entries":[
      {
     "type":"error",
     "status":409,
     "code":"item_name_in_use",
     "context_info":{
        "conflicts":[
           {
              "type":"file",
              "id":"2990420477",
              "sequence_id":"0",
              "etag":"1f64ca909178de30bc682a4ca2d14444719cf9a2",
              "name":"Extensions.pdf"
           }
        ]
     },
     "help_url":"http:\/\/developers.box.com\/docs\/#errors",
     "message":"Item with the same name already exists",
     "request_id":"1389504407503c7c1e8183c"
      }
   ]
}

Answer 1

We are in the process of changing this from a 200 to a 202. Later this week (or possibly tonight) we’ll roll out a change to make upload statuses be 202’s, to show that the upload request has been accepted. I’ll post a bit more on our blog to explain more details.

The basic logic is that uploads can be sent in bulk, and the API call has to return you an array of upload statuses (stati?). If you only upload one file, you’ll get an array of 1, and you’ll have to dig into the array to see if you were successful or not. If you upload a group of files, then you’ll be digging into the array to find out the status of each file.

You might ask: Why not collapse the status when there is only one file? Our thought there is that you’d have to implement 2 different code paths to deal with single vs bulk-upload, and it would be easier to just write the code once to handle uploads either way.

Hope that helps. Let us know if you see unexpected behavior after we flip the error code over from the 200 to the 202.