Which http status codes to use when processing http post?

Question

I have a HTML form, which I submit via http post.

There are two cases:

• Case 1: The data is valid and data on the server will be updated accordingly
• Case 2: The data is invalid and the http response contains an error message for the user.

Which http status codes should be used for each case?

I use htmx to submit the form. This means I don't need to use the POST/Redirect/GET pattern.

This question is not about JSON-APIs.

Answer 1

I'm using htmx 1.8 with asp.net core 6.0. This works for me.

controller:

    //server side validation failed 
    Response.StatusCode = 422;
    return PartialView("Core", product);

client side javascript:

document.body.addEventListener('htmx:beforeOnLoad', function (evt) {
if (evt.detail.xhr.status === 422) {
   //
   // allow 422 responses to swap as we are using this as a signal that
   // a form was submitted with bad data and want to rerender with the
   // error messages
   //
   evt.detail.shouldSwap = true;
   evt.detail.isError = false;
   }
});

Answer 2

The complete list of HTTP response codes published by the Mozilla Foundation is pretty comprehensive and easy-to-read, so I'd recommend always consulting it as a guide. For the generic use-cases mentioned by you, there are a couple of different codes you can return - depending on what happens with the data on the server, and what you want to happen in the user's browser.

CASE 1: data is valid, data on server is updated

Base on your short description, the different status codes that might be applicable are:

• 200 (OK): you are updating an existing record on your own server - eg., the user is submitting a form which updates their existing contact information on your website - and information was received, and the record updated successfully. The response would usually contain a copy of the updated record.
• 201 (Created): you are not updating an existing record, but rather, creating a new record on your server - eg., your user is adding a new phone number to their contact details, which is saved in your database as a separate 'phone' record. The response should contain a copy of the newly created record.
• 205 (Reset Content): the same as 200, but implies that the browser view needs to be refreshed. This is useful when the record that is being updated has values that are dynamically calculated by the server, and which might change automatically depending on the values you're submitting. For example, if you have a user adding extra information to their online profile, which might grant them special status, badges and privileges on the website. This means, that if the user is viewing their profile information, that information will need to be updated with the new 'status' automatically granted by the server. The 205 response body will normally be empty, which means that to update the browser view your response-handling code will need to:
  • do further ajax requests and update the relevant part(s) of your interface with new information from the server, or
  • redirect the user to a new URL, or
  • reload the entire page.

If working with HTMX, a 200 or 201 response would include the actual html snippet of the record that you want updated on the page - and HTMX will replace it automatically for you when it receives the response. With a 205 response, you could send an HX-Trigger response header that would call a custom event on the interface elements that need to update themselves - see the examples in the docs.

CASE 2: data is invalid, data on server is not updated

The status code that needs to be returned in case of an error varies depending on what caused the error. Errors that the server believes are the responsibility of the client - such as 'sending invalid data' - have a status code in the 4XX range. Some of the common errors in that range include 404 ('Not Found'), 403 ('Forbidden'), and 'Unauthorised' (401).

In the case of a client sending data that the server cannot process because it is 'not valid' - either because the request itself is malformed, or because the data doesn't pass some business validation logic - the current advice is to return status 400 (Bad Request).

Many years ago, some people believed that the status code 400 should only be used to indicate a malformed request (syntactical error) - not to indicate a failure in business validation logic (semantic error). There was a lot of debate, and temporarily a new status code (422) was created, that was supposed to cover semantic errors, exclusively. In 2014, however, the official definition of the status 400 code was changed to allow for the inclusion of both syntactical and semantical errors - which rendered status 422 essentially unnecessary.

You can find lots of discussions and explanations online about the differences between 400 and 422, and some people still argue passionately about this to this day. In practice, however, the 400 code is all you'll need - and you can include a response body in it that explains in detail, if needed, the cause of the error.

Note that when working with HTMX, a response with a 400 code should trigger an htmx:responseError event automatically. You can trap that event, for example, to update your form interface elements, in case of data validation errors caught by the server.

Answer 3

You have said it is not about JSON APIs, but how will you meet this type of requirement - it is not clear whether this is relevant for your scenario???

SERVER DRIVEN BEHAVIOUR

I cannot see how a client could ever decide an HTTP status code based on input data. How would the client deal with these examples?

• The call is not authenticated (cookie or token) - an API would return 401 - this tells the UI to perform a retry action.

• The call is not authorized - an API would return 403 or 404 and the UI would present an error display.

• The data is malformed or invalid according to domain specific checks - an API would return 400 and tell the UI what is wrong so that it can perform actions.

• Something went wrong in server processing, eg data cannot be saved because database is down.

MY THOUGHTS

htmx looks interesting but a key requirement before using it would be ensuring that htmx can read server side error responses and use values returned. Maybe there is an elegant way to do this ...

Maybe I am just paranoid :). But it is worth being careful when choosing technologies that there are no blocking issues. Lack of error handlng control would be a blocking issue in most systems.

Answer 4

Well, 200 OK and 201 Created are the best for successful result.

For invalid data I would return 422 Unprocessable Entity, because the headers are correct, but body is not (though parseable by the server). The caveat is some HTTP clients won't handle 422 properly and in this case you have to use 400 Bad Request, however, the most of the modern clients will be fine.

Answer 5

200 OK or 201 Created are the best choice for a successful POST request.

However, for invald data, you can pass 415 Unsupported Media Type