15

What HTTP response code should be returned when a POST request was not successful and a request body was correctly formatted?

For successful POST request i am using 201 - Created, but there is no equivalent not created code.

I am thinking either 400 - bad request but that would actually point user that a request is poorly formatted or 304 - not modified.

mko
  • 6,638
  • 12
  • 67
  • 118
  • 2
    You've told us what was right with the response, but you haven't told us what was wrong with it. Why wasn't it successful? – Quentin Nov 13 '17 at 16:58
  • 2
    Do you mean the request has failed because the payload format was correct but the data was invalid? Go for `422`. – cassiomolin Nov 13 '17 at 16:59
  • @Quentin you have a good point there. What could go wrong on POST request, what are all the fail scenarios? And what is worth capturing as a status code and what should go under "miscellaneous" or 500. – mko Nov 13 '17 at 17:38
  • Using PyMongo, I've trapped and reported every error from Mongo or the API with 400's and 500's, particularly `HTTP_503_SERVICE_UNAVAILABLE` if I think the upstream Mongo service is having temporary conniptions, but it's still possible for Mongo to go through all that, including schema validation, and just come back "no", write not acknowledged, no description of error, just didn't happen. I guess under these circumstances I would just make this another `513`, but I'd still really like to have another code. And BTW shouldn't `HTTP_418_IM_A_TEAPOT` actually be `HTTP_418_YOURE_A_TEAPOT`? – NeilG Jan 18 '23 at 03:09

1 Answers1

18

What HTTP response code should be returned when a POST request was not successful and a request body was correctly formatted?

If you mean the syntax of the request payload is valid but it cannot be processed due to invalid data, you can use 422:

11.2. 422 Unprocessable Entity

The 422 (Unprocessable Entity) status code means the server understands the content type of the request entity (hence a 415 (Unsupported Media Type) status code is inappropriate), and the syntax of the request entity is correct (thus a 400 (Bad Request) status code is inappropriate) but was unable to process the contained instructions. For example, this error condition may occur if an XML request body contains well-formed (i.e., syntactically correct), but semantically erroneous, XML instructions.

Remember to provide a good description in the response payload explaining what's wrong with the payload. Refer to the RFC 7807 for details on how to report problems in HTTP APIs.

Updates (according to the comments)

The reason why a POST request would fail is more of a business logic error, for example "account balance too low to withdraw 5.00 USD".

For the situation described in your comment, 403 or 409 would be a better fit.

6.5.3. 403 Forbidden

The 403 (Forbidden) status code indicates that the server understood the request but refuses to authorize it. A server that wishes to make public why the request has been forbidden can describe that reason in the response payload (if any). [...]

6.5.8. 409 Conflict

The 409 (Conflict) status code indicates that the request could not be completed due to a conflict with the current state of the target resource. This code is used in situations where the user might be able to resolve the conflict and resubmit the request. The server SHOULD generate a payload that includes enough information for a user to recognize the source of the conflict. [...]

Community
  • 1
  • 1
cassiomolin
  • 124,154
  • 35
  • 280
  • 359
  • I accepted this answer but after running into same issue again, and after I read you answer again, it doesn't seem like a valid answer. The reason why a POST request would fail is more of a business logic error, for example "account balance too low to withdraw 5.00 USD". This is not a 400 error since request is well formatted, it is not 5XX error since nothing is wrong with , so what type of http error code is it? – mko May 14 '18 at 12:14
  • @mko Your question was not specific, that's the reason why I stated _"If you mean..."_. For the situation described in your comment (_"account balance too low to withdraw 5.00 USD"_), [`403`](https://tools.ietf.org/html/rfc7231#section-6.5.3) or [`409`](https://tools.ietf.org/html/rfc7231#section-6.5.8) would be a better fit. – cassiomolin May 14 '18 at 12:27
  • 1
    hm, this doesnt sound right. If an API request fails on business logic level, would it be considered as a http error. Would a correct way be to return a 2XX success code, and then provide some kind of a warning/error message about request not passing business rules. As an alternative closest http status code would be 304 Not Modified (RFC 7232). – mko May 14 '18 at 14:25
  • @mko It's a [client error](https://tools.ietf.org/html/rfc7231#section-6.5) and any [`2xx`](https://tools.ietf.org/html/rfc7231#section-6.3) status codes would fit here. In a similar way, [`304`](https://tools.ietf.org/html/rfc7232#section-4.1) is not suitable for this situation. – cassiomolin May 14 '18 at 14:30