SCS2: Non-VOTable errors?

[Markus Demleitner]

Dear DAL folks,

two weeks ago I advertised the SCS2 working draft
<http://mail.ivoa.net/pipermail/dal/2026-June/008878.html>; interest
at least week's interop was good, so I think we ought to go ahead.

As promised two weeks ago, I'd like to bring up points from Stelios'
feedback
<https://github.com/msdemlei/scs2-original-deleteme/issues/2> [1]
in suitable packages, and I'll start with one we've discussed a bit
at the Interop already:


> The spec is clear on this "all responses, including errors, must be
> in VOTable unless the client has requested a different
> RESPONSEFORMAT."
>
> While I do see the benefits, and it does give clients a single
> parsing path for both successful and error responses, this
> requirement makes writing services with modern HTTP frameworks
> awkward.
> FastAPI for example, automatically generates JSON validation errors
> with HTTP 422 responses.
>
> Overriding this to produce VOTable requires custom exception
> handlers for every error path and I would argue is a hurdle that
> goes against the "implementable within a week" target because you
> end up fighting against the frameworks and their own validation
> mechanisms.
>
> Also, since we define any client behavior that requires parsing
> error bodies in a structured way, I don't really see a huge win for
> clients being able to parse the error body, versus just showing it
> as it is came in the user.
>
> I'd argue that the HTTP status codes are more important for the
> client and already carry the machine-readable signal (400 = bad
> parameters, 422 = invalid values). They can then choose to either
> display information just based on the status code, include the
> extra context either by default or as a "Extra information on the
> error" button, and then potentially even parse the response if it
> comes in a format they can deal with. (Existing clients who know
> VOTable parse and return the relevant text, if they get JSON they
> can either parse it or just show it as JSON)
>
> I see the error body is advisory context and I think the format is
> a convenience choice, and by forcing it to be VOTable creates an
> implementation burden for service authors using modern HTTP
> frameworks.
>
> My take is that the requirement to produce VOTable errors should
> either be relaxed to allow any human-readable format for 4xx
> responses, or the spec should define the IVOA should define use
> cases that make VOTable parsing of error bodies necessary.

First off: What SCS2 right now says is basically what DALI has, and I
think whatever we decide here should be fed back to DALI.

Then, my minimal requirement is that *if VO code comes into play at
all*, clients should ideally have one clear way to get a string to
display to the user when something goes wrong.  Perhaps I can live
with two ways, but when clients have to expect three different
formats in which services report errors, I'd raise a veto.

This clearly is different when the VO code doesn't even get to
respond; of course there are network timeouts, 504 from reverse
proxies and a bunch of other nastyness that may very well lead to
ugly, ununderstandable diagnostics.  But that we can't help as long
as we operate over a network, so let's concentrate on what we can
help.

Meanwhile, Joshua has posted the sort of code they need to turn
messages from their framework into VOTables at
<https://github.com/msdemlei/scs2-original-deleteme/issues/2#issuecomment-4650305818>.

My thoughts on this are: This is not insane code by any measure.  On
the other hand, if we allow multiple sorts of error responses, this
kind of work will need to be done in each client.  I feel pushing
responsibility there would be a bad move because:

(1) Clients are a scarce resource; let's make it easier for them

(2) The error parsing paths on the client side generally are much
less well-tested than the good path, and hence it's much more likely
that this stuff will be broken.  Getting wild errors and tracebacks
when, really, something else is wrong is the sort of user experience
that makes people hate the world.

(3) If it's done on the server side, validators can much more easily
catch gross errors.

But that's not *much* more than my 2 cents.  I would, for instance,
be open to Datalink-style error messages (controlled vocabulary term:
human-readable explanation) as well.  It's a bit ugly that
QUERY_STATUS signalling then become asymmetric between good and
failing requests, but then the VOTable wrapping of diagnostics isn't
too pretty either.

Other thoughts?

Thanks,

          Markus

[1] If anyone can move this bug to the new SCS2 repo, please do so;
it seems I can't.