API: Differentiate between "not found" and errors

From my point of view a "XY not found" is not an error. At the current state of the API it is hard to differentiate between "XY not found" and an error (except by parsing error messages -> what I don't dare to do).

Example requirement

👉 Return a project if it exists or create it otherwise.

As far as I know this very simple requirement is not possible with the current API implementation!

Given the project doesn't exist: Trying to retrieve the project to check if it exists and to potentially return it would yield a unrelatable error response that I'm unable to handle properly.

Given the project does exist: Just trying to create the project every time would also yield a error but wouldn't return the actual existing project.

Proposal

If I access XY with the necessary and validated permissions and non other error appears but the requested XY doesn't exists:

• return a empty response
• OR return a specific error code that can be handled (if 404 and 204 are used for anything else then introduce a new 9xx custom error code)

~"feature proposal" api