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 a201
(Created) response containing aLocation
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 aLocation
header field in the response or, if noLocation
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 aHEAD
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 indicatedContent-Type
orContent-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 aHEAD
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.