resthttphttp-status-codeshttp-status

Which HTTP status should I return if the client tries to upload a new file while server is still processing the previous one?


My application has a button for allowing the user to upload a file. Uploading the file is very quick, we send the response to the client very quickly, but the service takes a while to process it.

The user can only upload a new file when the previous one is already processed. Therefore, if the user tries to upload a file while the server is still processing one, we should return an error to the client.

My question is which HTTP response status should I use? I checked all options and these are the ones which I believe are closer to my situation:

Which one do you believe is the most appropriate to this situation? Or any of them, should I use another one?


Solution

  • Which one do you believe is the most appropriate to this situation?

    429 Too Many Requests

    The 429 status code indicates that the user has sent too many requests in a given amount of time ("rate limiting").

    The response representations SHOULD include details explaining the condition, and MAY include a Retry-After header indicating how long to wait before making a new request.

    429 Too Many Requests
    Retry-After: 60
    Content-Type: text/plain
    
    Why don't you wait a minute?
    

    Why I'm not advocating for any of the codes you recommended:

    425 Too Early ; I would avoid this one as it seems to be specific to the context of early data.

    428 Precondition Required ; the core problem here is how to communicate to a general purpose client which precondition should be included in the request. Also, it's a little bit off, semantically.

    409 Conflict ; in practice, you might be able to make this one work. Semantically, the difficulty is that there really isn't a way for the client to resolve the conflict (ex: reloading the page to get a fresh copy of the server's copy of the resource).


    The important thing to recognize is that HTTP status codes are only incidentally for humans. Status codes are metadata of the transfer-of-documents-over-a-network domain; the intended audience is general purpose HTTP components (browsers, spiders, caches, proxies, etc).

    Therefore, the "best" code to use is going to be that code which tells general purpose components the right thing. Specialization happens in the response body, where we use the payload to communicate the fine grained details.