SCS2: Non-VOTable errors?

[Patrick Dowler]

In my opinion, the "errors in VOTable" were a simple but bad idea and
we should figure out how to stop requiring it. In detail, it was an
ill-conceived way for server and client to ignore the content-type
header in the response and then clients could just read with a VOTable
parser.

In other services with complex error messaging in the API (eg
VOSpace), content-type: text/plain and content like
   {vocab term}: {human readable explanation}
works very well and is simple. Clients could choose to display the
first line of that output (with an option to show additional lines if
the user wants to see more details). I haven't thought about other
structured error messages (eg json) but I expect we can't say anything
about the structure without creating work for people using a
framework...

So, I would strongly support updating DALI to say that error messages
can be in the requested format or text/plain; errors happen at other
layers in the stack and it's hard to mandate changing them. For
example, we run HAProxy front end and docker container backend(s); if
a container is down, HAproxy will output a 503 with a simple/useless
text/html response... ugh, but not worth the aggregate effort to do
anything about.

I could draft a change in DALI and we can decide if we delay
PR-DALI-1.2 to include it, or postpone to DALI-next. Thoughts?

--
Patrick Dowler
Canadian Astronomy Data Centre
Victoria, BC, Canada

On Thu, 18 Jun 2026 at 06:01, Markus Demleitner via dal <dal at ivoa.net> wrote:
>
> 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.
>