Thoughts on standardizing TAP timeout/error handling

[Markus Demleitner]

Dear Colleagues,

On Wed, Jul 16, 2025 at 04:52:46PM +0000, Stelios Voutsinas via dal wrote:
> <VOTABLE>
>   <RESOURCE type="results">
>     <INFO name="QUERY_STATUS" value="ERROR">Query exceeded processing time limit</INFO>
>     <INFO name="ERROR_TYPE" value="resource-limit"/>
>     <INFO name="ERROR_SUBTYPE" value="time-limit-exceeded"/>
>   </RESOURCE>
> </VOTABLE>
[...]
>
> Markus suggested this might be a good candidate for a standard
> vocabulary, which makes sense to me. And the approach seems
> extensible enough that we could add new error types later without
> breaking anything.

Actually, I was suggesting to *only* have ERROR_TYPE and make its
value controlled by a vocabulary.  In that way, thanks to the
hierarchy of the vocabulary, services can communicate types and
Stelios' subtypes in one go.  A part of the vocabulary could, for
instance, be:

  resource-limit-exceeded
    time-limit-exceeded
    disk-limit-exceeded
    network-transfer-limit-exceeded
    request-string-too-long  (though that probably ought to be HTTP-level)
  client-error
    parameter-syntax-error
      bad-adql
    missing-parameter

...and so on.

If a server says

  <INFO name="ERROR_TYPE" value="bad-adql"/>

a client that has first-hand knowlege of that term knows that there's
no point re-submitting this query (at least to that server) and
specifically, that their users need to check their query syntax.

Less sophisticated clients might only classify by the top-level
concepts, and I claim finding these is easy to do; cf.
https://ivoa.net/documents/Vocabularies/20230206/REC-Vocabularies-2.1.html#tth_sEc3.2.2

Basically, when the error type is in error_type and you have a dict
of predefined reactions error_actions, you would write something
like (actual Python):


  # Fetch the vocabulary
  import requests
  voc = requests.get(
    "http://www.ivoa.net/rdf/error-type",
    headers={"accept": "application/x-desise+json"}
  ).json()

  # find the most specific reaction ofr error_type
  while error_type not in error_actions:
    error_type = voc["terms"][error_type]["narrower"][0]

  error_actions[error_type]()

This will raise an IndexError if no appropriate action can be found,
but that's easy to change.

If good terms for that error-type vocabulary cross your mind while
you're thinking about this, please let me know.

Thanks,

              Markus