As an engineer working for the same company, I very much want to know, because I want to know if I did something wrong on my end, or if something is broken on your end.
When designing an API, certain conditions must return a 404 with no further explanation given. These are purely security concerns.
If you try to login with an email and a password, I will return a 404 with no further explanation if the auth request fails. Even if the email exists in the system. This will prevent abuse of the login mechanism to confirm what emails are valid and which are not. The same principle applies for other resources.
On the other hand, if you truly send a malformed request and explaining to you in what way it is malformed poses no security risk ... only a jackass would return a 404. I would send a 400 with a detailed explanation, so that you can fix it.
Auth is something different. You should return a 401 with no additional information indeed.
However, the point is that as an API client, you want to be able to distinguish between "this bookshelf does not contain book X" and "what are you talking about, there is no bookshelf here".
Yup, that's better.
> However, the point is that as an API client, you want to be able to distinguish between "this bookshelf does not contain book X" and "what are you talking about, there is no bookshelf here".
I suppose you can return a 403 if it's something you shouldn't be accessing, but then you're bleeding information. You're letting the client know that it exists, but they don't have permission to access it.
A scheme that checks for permissions first and defaults to 403 when they're insufficient regardless of the existence of the resource would work though.
I guess it depends on how you implement the entire system.
> The request could not be completed due to a conflict with the current state of the resource. This code is only allowed in situations where it is expected that the user might be able to resolve the conflict and resubmit the request. The response body SHOULD include enough information for the user to recognize the source of the conflict. Ideally, the response entity would include enough information for the user or user agent to fix the problem; however, that might not be possible and is not required.
If you consider the "current state of the resource" to be "it doesn't exist yet, but you could create it".
It seems useful to distinguish between requests that could be fulfilled if the database contained different things, and requests that couldn't.
There's already HTTP Status Codes for failed auth. Use those.