That’s not what HTTP errors are about, HTTP is a high level application protocol and its errors are supposed to be around access to resources, the underlying QUIC or TCP will handle most lower level networking nuances.
Also, 5xx errors are not about incorrect inputs, that’s 4xx.
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.
The parser in most APIs will automatically handle parsing responses for 400 errors, but if the logic fails due to data being wrong, what do you respond with? E.g you send a valid SSN but the database could not find the person, or you send a valid email, but bo such email was found.
You can send 4xx errors yourself too. If the client needs to change something about the request, that’s a 4xx, like 400 Bad Request. If the server has an error and it’s not the client’s fault, that’s a 5xx like 502 Bad Gateway.
The wikipedia listing of all HTTP codes is quite helpful. People also forget you can send a custom response body with a 4xx or 5xx error. So you can still make a custom JSON error message.
Obviously you can, and i do returm 4xx codes if the initial parsing, authentication or something else goes wrong im the controller, but once im in the next api, or any number of systems down the chain, im probably gonna return a 200 with a status with a tracking code. It’s proven, at least for us very helpful to find issues fast on both sides. To me getting a 4xx back when it’s step 6 our of 13 that is the problem in the API but the request itself is fine doesn’t seem meaningful and just makes customers assume things. I guess if every endpoint only does one thing, i’d probably do like you.
A 2xx means success to its requester. If you have an error in step 6 out of 13 that breaks the resource action, you shouldn’t be returning a success.
You might argue what to return and what kind of information to include in the response (like tracking numbers), but it shouldn’t be a 2xx and I don’t see how a misleading 200 would be more helpful than a 400 bad request.
I mean sure, in the strict meaning of the code-guides you are probably correct. Most problems stems for us at least from cross-reference issues which are normally configuration problems in the underlying system or other data-related issues. Those are often not neither the responsibility of the server or the client, and sometimes its both. There are often no code that is suitable to respond, and to just send “Bad request” when it’s a good request - does not make sense. Therefore i think it’s better to let badrequest be for bad requests, instead tell the client that sure, this is a good request but for this reason it didn’t work this time. This has to happen for it to work. Either i can do it with a simple structure in json with maybe 5 status codes and a message, or i have to figure out what 20 http status codes both i and the client has to implement and give them meaning that isn’t their intended meaning.
and to just send “Bad request” when it’s a good request - does not make sense
That’s when you use a 5xx status, then. The client doesn’t care how many other services you reach out to in order to fulfill their request. A 5xx code also covers failures in other parts of the system.
The customer expects a row to exist.
The server does not find it.
The customer sent a valid request, and it should exist according to the customer.
The server could not find it. It can find others, but not that one, so from the server perspective it’s the client that gave the wrong id.
If i always send a 404, the customer system think it did something wrong, which it didnt. Should they try to find the error on their side now, as it is a “client error”?
If i send a 500 every time, the customer will think the server is at fault, which it is. The server just could not find that row. What if the customer actually made an error, sending the wrong id, and i send the same code every time. It will be the servers fault every time the customer makes an error, and now they will never double check their inputs.
My point is, there is no nuance with these old codes. Obviously i will send a 500 for a caught exception and a 400 for a client error, but it is not always so easy.
error codes aren’t about who’s at fault… you don’t send a 404 because it’s the users or the servers fault. it’s information… a 404 says something doesn’t exist… it’s nobody’s fault; it just is
a 4xx says the request, if tried again without changes or external intervention, is unlikely to succeed
a 5xx says the request might have been fine but some other problem that you can’t control occurred so may be retried without changes at a later time
these are all standard things that are treated in standard ways by generic HTTP libraries… look at, eg axios: a javascript HTTP library that’s often thinly wrapped to build API clients… a 200 is just passed through as success, where 4xx and 5xx will throw an error: exactly what you’d want if you try to retrieve a non-existent object or submit a malformed payload…
this is standard behaviour for a lot of HTTP libraries, and helps people accidentally write better code - an explosion is better than silence for unhandled exceptions
That’s not what HTTP errors are about, HTTP is a high level application protocol and its errors are supposed to be around access to resources, the underlying QUIC or TCP will handle most lower level networking nuances.
Also, 5xx errors are not about incorrect inputs, that’s 4xx.
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.
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.
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.
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.
The parser in most APIs will automatically handle parsing responses for 400 errors, but if the logic fails due to data being wrong, what do you respond with? E.g you send a valid SSN but the database could not find the person, or you send a valid email, but bo such email was found.
You can send 4xx errors yourself too. If the client needs to change something about the request, that’s a 4xx, like 400 Bad Request. If the server has an error and it’s not the client’s fault, that’s a 5xx like 502 Bad Gateway.
The wikipedia listing of all HTTP codes is quite helpful. People also forget you can send a custom response body with a 4xx or 5xx error. So you can still make a custom JSON error message.
Obviously you can, and i do returm 4xx codes if the initial parsing, authentication or something else goes wrong im the controller, but once im in the next api, or any number of systems down the chain, im probably gonna return a 200 with a status with a tracking code. It’s proven, at least for us very helpful to find issues fast on both sides. To me getting a 4xx back when it’s step 6 our of 13 that is the problem in the API but the request itself is fine doesn’t seem meaningful and just makes customers assume things. I guess if every endpoint only does one thing, i’d probably do like you.
A 2xx means success to its requester. If you have an error in step 6 out of 13 that breaks the resource action, you shouldn’t be returning a success.
You might argue what to return and what kind of information to include in the response (like tracking numbers), but it shouldn’t be a 2xx and I don’t see how a misleading 200 would be more helpful than a 400 bad request.
I mean sure, in the strict meaning of the code-guides you are probably correct. Most problems stems for us at least from cross-reference issues which are normally configuration problems in the underlying system or other data-related issues. Those are often not neither the responsibility of the server or the client, and sometimes its both. There are often no code that is suitable to respond, and to just send “Bad request” when it’s a good request - does not make sense. Therefore i think it’s better to let badrequest be for bad requests, instead tell the client that sure, this is a good request but for this reason it didn’t work this time. This has to happen for it to work. Either i can do it with a simple structure in json with maybe 5 status codes and a message, or i have to figure out what 20 http status codes both i and the client has to implement and give them meaning that isn’t their intended meaning.
That’s when you use a 5xx status, then. The client doesn’t care how many other services you reach out to in order to fulfill their request. A 5xx code also covers failures in other parts of the system.
The customer expects a row to exist. The server does not find it.
The customer sent a valid request, and it should exist according to the customer.
The server could not find it. It can find others, but not that one, so from the server perspective it’s the client that gave the wrong id. If i always send a 404, the customer system think it did something wrong, which it didnt. Should they try to find the error on their side now, as it is a “client error”?
If i send a 500 every time, the customer will think the server is at fault, which it is. The server just could not find that row. What if the customer actually made an error, sending the wrong id, and i send the same code every time. It will be the servers fault every time the customer makes an error, and now they will never double check their inputs.
My point is, there is no nuance with these old codes. Obviously i will send a 500 for a caught exception and a 400 for a client error, but it is not always so easy.
error codes aren’t about who’s at fault… you don’t send a 404 because it’s the users or the servers fault. it’s information… a 404 says something doesn’t exist… it’s nobody’s fault; it just is
a 4xx says the request, if tried again without changes or external intervention, is unlikely to succeed
a 5xx says the request might have been fine but some other problem that you can’t control occurred so may be retried without changes at a later time
these are all standard things that are treated in standard ways by generic HTTP libraries… look at, eg axios: a javascript HTTP library that’s often thinly wrapped to build API clients… a 200 is just passed through as success, where 4xx and 5xx will throw an error: exactly what you’d want if you try to retrieve a non-existent object or submit a malformed payload…
this is standard behaviour for a lot of HTTP libraries, and helps people accidentally write better code - an explosion is better than silence for unhandled exceptions
https://www.loggly.com/blog/http-status-code-diagram/
That’s still a 4xx situation.