Clarification: rationale for returning HTTP 500 for invalid HTTPBackendRef

[ivanmatmati]

Hi,

I have a question about the rationale for returning HTTP 500 when an HTTPBackendRef is invalid (e.g. due to a missing ReferenceGrant, leading to RefNotPermitted).

The spec states that:

When a HTTPBackendRef is invalid, 500 status codes MUST be returned…

However, in this scenario:

• The client request is valid
• The backend may be healthy
• The failure is due to a routing/configuration constraint, not a runtime error

Using 500 could suggest an internal failure of the gateway, while 503 might suggest backend unavailability — neither seems to precisely reflect the situation.

Could you clarify:

• What was the motivation for choosing 500 here?
• Was this mainly for consistency across implementations?
• Were alternative status codes considered?

Thanks!

[youngnick]

The motivation was basically:

• 400-class errors are not correct, because the problem originates with an intermediate
• it has to be a 500 class error of some kind for the same reason
• There's no existing 500 class error that exactly matches
• So, we went with 500.

Mandating the exact error code is exactly because we want to ensure consistency across implementations, so that we can test in the conformance tests.

Alternative status codes were considered, but as I said above, were not suitable for various reasons.

[youngnick]

Oops, sorry, hit the wrong button and closed.

Overall, I'd summarize "Why 500?" as "It's not a client error, or a server error, it's a routing/proxy error, so 500 is the only viable option."

It's also imperative that we actually do return some error in these cases, because otherwise canary rollouts and weights would not have the desired effects.

[oktalz]

hi @youngnick

yes, some error, but 500 is literally its servers fault and server does not really know why 500 Internal Server Error - but we do know why -> grant does not allow it, its forbidden.

I'm not really sure we want to follow this, I know in advance people will complain that seeing 500 seems like something is wrong and it should be correct while in fact it is not allowed.

RefNotPermitted seems more like its unauthorized or forbidden (and you literally have Not Permitted in name and that is exactly that)

if user is not allowed to access it due to grants it is almost the same as having RBAC on some rest API, you do not get 500, you get 403 or 401 or something similar. Its not servers fault you do not get access to resource.

[youngnick]

Just to reiterate, the classes of error we have available in HTTP are:

• Informational Responses (100-199)
• Successful Responses (200-299)
• Redirection messages (300-399)
• Client error messages (400-499)
• Server error responses (500-599)

The only ones that are at all candidates are 4xx class, or 5xx class.

These errors are supposed to be from the client's perspective as well.

So they are definitely not any 4xx class, because the client did nothing wrong. The server (here meaning the combination of the Gateway plus the backend it's forwarding to), was unable to fulfil the client's request. From the client's point of view, then 500 is fine because it tells the client that "something went wrong and it's not your fault".

401 or 403 would not be correct, because it's not that the client is Unauthorized or Forbidden, it's that the Gateway (which, again, serves as the Server here) is unable to complete the request.

So, that leaves us with 500 class errors, and all of the other 5xx errors don't work in this context (that the intermediate proxy is misconfigured or unavailable). Sometimes the reason might be better described by specific errors, but again, we need to ensure the same behavior across all implementations, reliably, so we chose 500.

To put this another way - in this case, the "server" is the Gateway, and it is the Gateway's fault that the request cannot succeed. Its config is incorrect or incomplete, and so it cannot service the request.

Also, RefNotPermitted is that the reference inside the configuration is not permitted, so the configuration is invalid. The configuration being invalid is what produces the 500 error.

I hope this helps understand this thought process better.

[oktalz]

I hope this helps understand this thought process better.

yes, it helps, although it might not help with changing my opinion

then 500 is fine because it tells the client that "something went wrong and it's not your fault".

in my experience users read 500 as "something is broken, fix it," not as a deliberate policy signal. That's part of why this matters.

401 or 403 would not be correct, because it's not that the client is Unauthorized or Forbidden, it's that the Gateway (which, again, serves as the Server here) is unable to complete the request.

"unable to complete the request" => because it is forbidden !

the reason it can't be completed is precisely that it's forbidden by an explicit admin choice. Different mechanism than 401/403, sure, but the nature of the refusal is the same: someone deliberately did not grant access.

Also, RefNotPermitted is that the reference inside the configuration is not permitted, so the configuration is invalid. The configuration being invalid is what produces the 500 error.

That's not misconfiguration; that's an access decision.

The HTTPRoute is perfectly valid. What's missing is a ReferenceGrant — i.e., a permission that the target namespace's owner chose not to issue.

I get that status codes are hard and implementers disagree. But I struggle to see how a deliberate "is not permitted" maps to "not your fault." It's not the user's fault in the same way a missing auth token isn't the user's fault — both are admin choices about who gets access.

[howardjohn]

@oktalz in my (highly subjective) opinion 403 implies the user calling the API is not authorized. RefGrant means the Route creator messed up. That's a big distinction and also probably not something you want to expose to users

[oktalz]

@oktalz in my (highly subjective) opinion

Just to echo that, my view is subjective too, though it comes from what I've observed in practice.

RefGrant means the Route creator messed up.

I can see that interpretation, but I'm not sure it always holds. A missing grant can also be a deliberate choice on the namespace owner's side, which is really where the tension lies. If we assumed a missing grant were always a mistake, then arguably we wouldn't need grants at all, we could just default to allowing access.

The other consideration is that there's a conformance test covering this behavior (and it isn't the only one). So it does seem to be planned by spec. If the spec plans for it, I'd find it hard to frame the same scenario as a mistake on the user's side.

I fully agree that 403 may not be the perfect fit, and we will explore alternatives. My main concern is just that 500 feels heavier than what the situation warrants. Today we might even surface a 404 in some cases. Either way, something will be exposed to the client, whether 4xx or 5xx.

It's also worth noting that HTTP status codes weren't really designed with three parties in mind, they are a contract between client and server, and the implementation isn't really the server here, the end service is. That's part of why I think there's room for interpretation, and reasonable people will land in different places on what 500 should mean.

That said, mandating 500 by design just feels a bit strong from my perspective, coming back to the "something is broken, fix it" mental model a user typically has, when in this case there isn't really anything for them (or admin) to fix.

And ultimately, even if the spec stays as-is, that's completely fine. It would mean slightly less coverage on our side, but I never expected us to cover everything, and given the spec itself defines multiple feature support levels, I don't think it expects that either.

It would also mean a bit more documentation work on our side, to explain why certain features are supported in practice but not listed as such, but that is a reasonable trade-off.

[youngnick]

For some of these, the conformance tests require a 500, and those parts of the API are stable and won't be changed. I understand your concerns, but to an extent, this contract is already agreed on by the community, and has been for some time, so I don't think there is enough gain to be worth changing it (if we even could, because, again, stable API).

I encourage you and any other implementers to use the conformance tests as the system of record for correct behavior, that's what they're intended for.

However, the fact is, there is something to fix. Someone, somewhere has to make a configuration change to fix this error. And that someone is not the client whose request has arrived at the Gateway. So, one of 4xx errors is not correct. This is a configuration error. That's the other reason why this won't be changing.

Thanks for the discussion, I think it's illuminating.