Rationale for Mapping FAILED_PRECONDITION to HTTP 400 Instead of 422

[yordis]

Hi team,

Could you please clarify the rationale for why FAILED_PRECONDITION in the canonical error model is mapped to HTTP 400 rather than HTTP 422 (Unprocessable Entity)?

From an HTTP semantics perspective:

• HTTP 400 typically indicates syntactically invalid requests.
• HTTP 422 is intended for requests that are syntactically correct but semantically invalid (e.g., domain rules violations).

Since FAILED_PRECONDITION often signals that the request is well-formed but violates a business rule or invariant, using 422 seems more aligned with HTTP semantics.

Is there a specific reason why 400 was chosen as the mapping?

Thanks for any insights you can share on this design decision.

From: #67 (comment)

There is a discussion on the aforementioned internal link from [name redacted], who argues (most likely similarly to this customer) that mapping to 412 would have been a better result for users, regardless of what the spec says. There is a decent case to be made for this, but since ESF has been converting FAILED_PRECONDITION to 400 for five years now, there is likely no way we can reasonably change this -- it would be a massive breaking change.

[yordis]

@1xX69 thank you so much for the link.

Now, I am even more confused in terms of what FAILED_PRECONDITION is meant to be used for,

1. Is it for the sake of 412?
2. Is it for the sake of 422?

@1xX69 thank you so much for the link.

Now, I am even more confused in terms of what FAILED_PRECONDITION is meant to be used for,

1. Is it for the sake of 412?

2. Is it for the sake of 422?

15.5.13. 412 Precondition Failed
15.5.21. 422 Unprocessable Content

FAILED_PRECONDITION isn't header-specific like HTTP 412. Also not sold on HTTP 422—it seems more about request content than server state. Still, if we avoid custom 4xx codes, 422 might be our best option.

From RFC 9110:

HTTP status codes are extensible. A client is not required to understand the meaning of all registered status codes, though such understanding is obviously desirable. However, a client MUST understand the class of any status code, as indicated by the first digit, and treat an unrecognized status code as being equivalent to the x00 status code of that class.

On a different note, we could add a new gRPC spec requirement: client SDKs and user apps shouldn't rely on HTTP status codes. Why bother anyway? They're unreliable due to collisions (e.g. both FAILED_PRECONDITION and INVALID_ARGUMENT => HTTP 400). We could still allow checking just the response class though (the first digit).

P.s It seems like user apps shouldn't trust gRPC codes either lol. Since they may stack, are they even useful? 😅 Maybe they should indicate only the response class (the first digit in HTTP status code)... but that raises a new puzzle: Could distinct response classes ever collapse into a single code? 🤔

[yordis]

it seems more about request content than server state.

😭 the renamed to Unprocessable "Content" which now, I question my decade+ career using 422 in Rails, Phoenix and things like that 😭 My life is a lie!

On a different note, we could add a new gRPC spec requirement: client SDKs and user apps shouldn't rely on HTTP status codes. Why bother anyway?

Fair point, and honestly, I really do not care as much other than understand the decision-making, others will ask me the same question I wouldn't know, other than pointing to Google RPC specs, and decided to align with it.

As you said, SDKs are in between these technicalities anyway.

Althou, what I do-do care is to know when it was a Domain specific failure or a completely broken payload that shouldn't be send again

Could distinct classes ever collapse into a single code? 🤔

What do you mean by classes here?

it seems more about request content than server state.

😭 the renamed to Unprocessable "Content" which now, I question my decade+ career using 422 in Rails, Phoenix and things like that 😭 My life is a lie!

On a different note, we could add a new gRPC spec requirement: client SDKs and user apps shouldn't rely on HTTP status codes. Why bother anyway?

Fair point, and honestly, I really do not care as much other than understand the decision-making, others will ask me the same question I wouldn't know, other than pointing to Google RPC specs, and decided to align with it.

As you said, SDKs are in between these technicalities anyway.

Althou, what I do-do care is to know when it was a Domain specific failure or a completely broken payload that shouldn't be send again

Could distinct classes ever collapse into a single code? 🤔

What do you mean by classes here?

Thank you for catching the typo! I was going to say "the class of response." It's the term I brought from RFC 9110. (15. Status Codes, The first digit of the status code defines the class of response.)

In different words, I was asking whether 4xx could ever collapse into 5xx. And something tells me that it's a possible scenario. It would be reasonable to prefer INTERNAL (HTTP 500) over FAILED_PRECONDTION (HTTP 400) or over any other 4xx error.

I feel like the gRPC codes... they aren't even useful... and so... can be removed? (Maybe not in the official repo because it would be a massive breaking change, but in a forked, reinvented version of gRPC.)

My assumptions:

DATA_LOSS: Can be conveyed via ErrorInfo.
UNAVAILABLE: Can be conveyed via ErrorInfo.
UNKNOWN: Can be conveyed via ErrorInfo.

I haven't took all the other codes into consideration yet. But, at a first glance, it seems like many of them can be removed, if not all!

[yordis]

I think that, in the practical sense, most errors are FAILED_PRECONDITION and let the mapping be, it is what it is then

I honestly do not care as much about the status, as long as the usage is correct, which is what I am trying to also figure out.

It is related to https://github.com/TrogonStack/trogonerror/ btw, I am trying to add a direct google.rpc integration.

I think that, in the practical sense, most errors are FAILED_PRECONDITION and let the mapping be, it is what it is then

I honestly do not care as much about the status, as long as the usage is correct, which is what I am trying to also figure out.

It is related to https://github.com/TrogonStack/trogonerror/ btw, I am trying to add a direct google.rpc integration.

I noticed you already mapped FAILED_PRECONDITION to 422. See also #837 (comment).

The Code primitive now feels redundant since #1088. I've decided to remove it from my own RPC implementation for now.

[yordis]

@1xX69 right, but the ADR is "wrong", primarily because I rather stick to Google RPC that change things, the intent of the ADR is to document the situation more than anything and deal with whatever decision making.

I don't want to create yet another spec.

The code still useful to setup o11y metrics, and things like that IMO

[yordis]

@jskeet maybe you can share some thoughts here? 🙏🏻

[jskeet]

No, I have no insight into this I'm afraid.

This might be relevant https://news.ycombinator.com/item?id=13707821

@1xX69 right, but the ADR is "wrong", primarily because I rather stick to Google RPC that change things, the intent of the ADR is to document the situation more than anything and deal with whatever decision making.

I don't want to create yet another spec.

The code still useful to setup o11y metrics, and things like that IMO

Agreed, the HTTP mappings aren't totally useless. They can be used to handle retries in the service mesh. But honestly, that seems like the only reasonable use case for them right now. The o11y metrics can be delegated to the application layer.