Standardize a response body across your APIs that specifies the cause of the non-2xx response. Have an enum per API/service for causes. Include them in the API doc.
If anyone still doesn’t get it, quietly dispose of them at your friend’s pig farm.
And it’s not even always a simple case of “that resource doesn’t exist”. A 404 could also mean that the resource does exist but the current authenticated user doesn’t have the correct permissions to access it, so it’s more like “as far as you know that resource doesn’t exist”. Some people might argue that 403 should be used for that, but then you’re telling potential bad actors that maybe shouldn’t even have access to your documentation that they have indeed found a valid endpoint.
Avoiding 403 seems like a security through obscurity approach to me.
I suppose there might be some special admin only endpoints you’d want to 404 on if the user is not an admin. But for most cases it’s really hell integrating an API that 404s on everything… is my token invalid, did I set a parameter wrong, or did I get the path wrong? I guess I gotta spend all day doing trial and error to figure it out. Fun!
Also makes integration tests on your security unreliable. Someone renames an endpoint and suddenly your integration tests aren’t actually testing security anymore. Checking for 403 and getting a 404 because someone renamed something will indicate the test needs to be updated to use the new path. Checking for 404 (because the user isn’t supposed to have access) and getting 404 (because the path was changed) means your test is useless but you won’t know it was rendered useless.
Some osint tools use this : they test an email on thousands of services, and use the error result (403/404) to know if the person has an account there.
It depends on the context. If it’s an URL that is easy to guess and reflects user-created content, your system is leaking information about their users if it returns 403. The example that comes to mind is GitHub returning 404s for both nonexisting and private repos when the authenticated user doesn’t have access to it.
404 is for “I can not confirm this resource exists”
For example, a private github repo must return 404 for unauthorized users, API requests must act as if that repository doesn’t exist (including returning 404 status codes).
403 is for “I can confirm this resource exists, you cannot access it”
I usually treat a path as a series of dereference operations, each with a potential security precondition. You could protect /secure/… with credential checks, and report 403 at that point, before even looking at the rest of the resource path. It exposes the prefix but not the multiple endpoints that might exist below that point.
I’ve had fellow developers fight me on this point, in much the same way as your parent post.
“If you return a 404 for a record not found, how will I know I have the right endpoint?”
You’ll know you have the right endpoint because I advertised it—in Open API, in docs, etc.
“But, if
/users/123returns a 404, does that mean that the endpoint can’t be found or the record can’t be found?”Doesn’t matter. That resource doesn’t exist. So, act appropriately.
It’s not like you can’t return a body with the 404 that specifies that the user itself is not found versus the ending being wrong.
Standardize a response body across your APIs that specifies the cause of the non-2xx response. Have an enum per API/service for causes. Include them in the API doc.
If anyone still doesn’t get it, quietly dispose of them at your friend’s pig farm.
And it’s not even always a simple case of “that resource doesn’t exist”. A 404 could also mean that the resource does exist but the current authenticated user doesn’t have the correct permissions to access it, so it’s more like “as far as you know that resource doesn’t exist”. Some people might argue that 403 should be used for that, but then you’re telling potential bad actors that maybe shouldn’t even have access to your documentation that they have indeed found a valid endpoint.
Avoiding 403 seems like a security through obscurity approach to me.
I suppose there might be some special admin only endpoints you’d want to 404 on if the user is not an admin. But for most cases it’s really hell integrating an API that 404s on everything… is my token invalid, did I set a parameter wrong, or did I get the path wrong? I guess I gotta spend all day doing trial and error to figure it out. Fun!
Also makes integration tests on your security unreliable. Someone renames an endpoint and suddenly your integration tests aren’t actually testing security anymore. Checking for 403 and getting a 404 because someone renamed something will indicate the test needs to be updated to use the new path. Checking for 404 (because the user isn’t supposed to have access) and getting 404 (because the path was changed) means your test is useless but you won’t know it was rendered useless.
Some osint tools use this : they test an email on thousands of services, and use the error result (403/404) to know if the person has an account there.
It depends on the context. If it’s an URL that is easy to guess and reflects user-created content, your system is leaking information about their users if it returns 403. The example that comes to mind is GitHub returning 404s for both nonexisting and private repos when the authenticated user doesn’t have access to it.
No.
404 is for “I can not confirm this resource exists”
For example, a private github repo must return 404 for unauthorized users, API requests must act as if that repository doesn’t exist (including returning 404 status codes).
403 is for “I can confirm this resource exists, you cannot access it”
I usually treat a path as a series of dereference operations, each with a potential security precondition. You could protect /secure/… with credential checks, and report 403 at that point, before even looking at the rest of the resource path. It exposes the prefix but not the multiple endpoints that might exist below that point.