elasticsearch
elasticsearch copied to clipboard
elastic
Solidify & document guarantees about structure of error responses
What guarantees do we offer about the formatting of exception responses? Today the docs give some examples but do not accurately describe the bits on which clients can rely, and our responses are quite different if the user sets http.detailed_errors.enabled: false which breaks clients that are overly strict about these things. It's unclear whether there are other situations that might result in differently-shaped error responses.
Some YAML tests assert things about error.type and error.reason and so on, but we don’t run those tests with detailed errors disabled (they would fail if we did). I believe there are more clients out there making decisions according to parts of the response (e.g. error.type) which may not always even exist, or may be unstable because they’re not covered by any tests.
It would be very helpful to clients if we could describe a general structure for error responses, and somehow guarantee that however we're configured we always follow the correct structure.
The ES team discussed this in our fix-it meeting on 2022-09-12. We saw lots of scope for improving our error responses, and associated API guarantees, but noted that in practice we don't come across many users that need more structure than we offer today.
We did however conclude that we should emit the same shape of response whether http.detailed_errors.enabled is set or not, and that we consider it a bug that we don't do so today.
We also decided that we should emit the reason field on all exceptions, even if the exception carries no message. Today this field is omitted if the exception message is null, but that almost never happens so we do encounter users that assume it is always present and deploy subtle client-side bugs as a result.
Finally, we agreed that we should document these guarantees properly once they're in place.
(edit: I'm labelling this for further discussion in the core/infra team about how to proceed now)
If so, I recommend leaving something in the associated code that mentions a version constant like Version#V_7_17_0 which will be removed in v9, since this will trigger a compile error which will help us not to forget to make this change.