Proper Http status codes for uploading files on rest end point

Question

We are developing an application that allows a user to upload file on rest end point.
Could someone please guide if it is correct to send 400 error code for the failure of following validation scenario:

1) The Length of file name exceeds permissible limit.
2) File name contains special characters
3) Uploaded file was empty
4) The System failed to read the uploaded file from disk.

Regards, Tarun

Solution 1

1. The Length of file name exceeds permissible limit.

I think the 400 is not an appropriate because syntax of the request is correct in this case. The 422 Unprocessable Entity is better in this case.

2. File name contains special characters

Illegal characters mean the syntax is broken. So 400 Bad Request is a proper response in this case. Someone may claim that a definition of illegal characters is needed so the server may authoritatively send 400.

3. Uploaded file was empty

I think it is not an error because an empty file is a legal file.

4. The System failed to read the uploaded file from disk.

Does the system mean the server? Then the server should return a 5xx response because it is not a client failure. In case of general read error the server should return 500.

EDIT:

Uploaded file was empty.

When application semantic forbids an empty file the 400 or 422 appropriate. More details about them is at 400 vs 422 response to POST of data

Solution 2

4xx statuses are for client-side errors, 5xx are for server-side errors. So, generally you need 4xx codes for your cases 1) to 3), while 4) should be a 5xx error.

Let’s first say that for your case 4), a simple HTTP 500 seems appropriate. If you want to indicate that the client could try again later, HTTP 503 would be more suitable.

Now for 1) to 3): According to RFC 2616, HTTP 400 indicates syntax errors; this would usually be protocoll errors, e.g. invalid headers. Semantical or payload errors aren’t really defined in this generic RFC, however, (as Zaboj mentions) WebDAV offers HTTP 422, which seems suitable, though it’s not really meant for generic HTTP.

In the end, it doesn’t really matter which particular codes you send. If your upload fails with HTTP 400 or 422, in either case the client will perform some error routine (e.g. show or log the error message).

The important thing to know is that some codes can trigger client behaviour (e.g. HTTP 401 combined with certain headers can trigger an authentication dialog in a browser), and you should be aware of these side effects.

In my opinion, it is much more important to send a useful error description in the response body to help the client fix their problem, than finding the “perfect” HTTP status code. I know that REST zealots will disagree, but none of them will be able to give you the right HTTP status code for every situation.

That said, if you want to issue fine-grained error codes/messages for automated processing, you can introduce custom HTTP header fields, e.g.

X-MyApp-Error-Code: 2.1.6
X-MyApp-Error-Message: The uploaded file is empty

Then you would provide a documentation and/or SDK which reveals all possible error code values for X-MyApp-Error-Code to your API consumers.

Comments

[Tarun]

Thanks. As per my application logic, It is not legit to upload empty file. What error should we send to client in such case.

[Tarun]

Would it be right to send ConflictHttpException if the uploaded file found to be empty

[Tarun]

Would it be right to send ConflictHttpException if the uploaded file found to be empty

[KevinTheGreat]

maybe for point 3 use 406 or 411, seeing as it somewhat comes close too empty files: en.wikipedia.org/wiki/List_of_HTTP_status_codes But that is only if an empty file is something you want to catch

[Tarun]

I got it. Thanks for your answer.

[lxg]

Not really. Symfony’s ConflictHttpException issues a HTTP 409. This code indicates conflicting access to a resource, e.g. if an upload would overwrite a (protected) file. As I said, don’t ponder too much about the “right” code … choose the right category (4xx vs. 5xx) and give a precise error message.

[Zaboj Campula]

@Tarun: ConflictHttpException is not an error code. It is and exception and developer may set a result code what she wants.

[Zaboj Campula]

@KevinTheGreat: 406 is not appropriate here imho. it indicates that the target resource does not have a current representation that would be acceptable to the user agent. 411 should be sent only if Content-Length is completely missing.