What HTTP status code should I return for POST when no resource is created?

Question

I am posting an image to my server (usign Java and Spring).

A couple of things can happen:

• If everything goes well, then I return 200 and the image id.
• The image can't be saved to the file system (SaveFileException).
• The database can't update the new image record with the new URL (DatabaseException).
• Or throw an IOException.

In short, I can not save/create the image.

What HTTP code should I return?

Should I return more than one code and more than one message according to the Exception?

Answer 1

First of all, let me highlight that status codes are meant to indicate the result of the sever's attempt to understand and satisfy the client's request.

If everything goes well, then I return 200 and the image id.

Seems to be fine, but I would advise you to return 201 along with a Location header instead. Quoting the RFC 7231 regarding the POST method:

If one or more resources has been created on the origin server as a result of successfully processing a POST request, the origin server SHOULD send a 201 (Created) response containing a Location header field that provides an identifier for the primary resource created and a representation that describes the status of the request while referring to the new resource(s).

Along with 201, the Location header is meant to indicate where the newly created resource is located. If no Location header is provided, then the client should assume that the resource is identified by the effective request URI:

6.3.2. 201 Created

The 201 (Created) status code indicates that the request has been fulfilled and has resulted in one or more new resources being created. The primary resource created by the request is identified by either a Location header field in the response or, if no Location field is received, by the effective request URI. [...]

---

Client error

Can the client perform a new request and fix the issue? If so, pick a status code in the 4xx range:

6.5. Client Error 4xx

The 4xx (Client Error) class of status code indicates that the client seems to have erred. Except when responding to a HEAD request, the server SHOULD send a representation containing an explanation of the error situation, and whether it is a temporary or permanent condition. These status codes are applicable to any request method.

Michael Kropat put together a very useful set of flowcharts that may give you some insighsts. See the following chart to determine the most suitable 4xx status code:

Some valid options, depending on what caused the error, are:

6.5.11. 413 Payload Too Large

The 413 (Payload Too Large) status code indicates that the server is refusing to process a request because the request payload is larger than the server is willing or able to process. [...]

6.5.13. 415 Unsupported Media Type

The 415 (Unsupported Media Type) status code indicates that the origin server is refusing to service the request because the payload is in a format not supported by this method on the target resource. The format problem might be due to the request's indicated Content-Type or Content-Encoding, or as a result of inspecting the data directly.

6.5.1. 400 Bad Request

The 400 (Bad Request) status code indicates that the server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).

---

Server error

If the error was caused by the server, then a status code in the 5xx range will be accurate:

6.6. Server Error 5xx

The 5xx (Server Error) class of status code indicates that the server is aware that it has erred or is incapable of performing the requested method. Except when responding to a HEAD request, the server SHOULD send a representation containing an explanation of the error situation, and whether it is a temporary or permanent condition.

See the following flowchart:

I would suggest 500:

6.6.1. 500 Internal Server Error

The 500 (Internal Server Error) status code indicates that the server encountered an unexpected condition that prevented it from fulfilling the request.

Answer 2

Depends on the issue that is preventing the image to be posted to server.

If the image or request are not formated correctly, should be 4XX.

eg: a general 400 Bad Request or specific 415 Unsupported Media Type, 409 Conflict, 413 Request Entity Too Large .

If the problem is a server side error, the error code should be on the 5XX:

eg. General one: 500 Internal Server Error or 503 Service Unavailable, specifics: 507 Insufficient Storage (WebDAV) 504 Gateway Timeout

Sometimes being specific about the error can help find a solution to make the POST work. But that depends if you want the error to be avoided and fixed.