Standardizing Timeout Error Responses

[stvoutsin]

As it stands and to the best of my knowledge TAP clients cannot reliably distinguish query timeouts from other failures.
Various services will return timeouts in different ways (different HTTP codes, error messages, connection drops).
This makes it very challenging for clients to identify, and perhaps recommend to a user an improved course of action.

An example of why standardizing this would be useful:
Many services have a short timeout for sync queries, but longer for async. A client interacting with this service
would then be able to identify that the sync query timed-out and either recommend use of async or implement some kind of retry logic.

Proposed Solution

Add something like this to DALI section 5.2 (Error Handling):

Services are urged to use HTTP 408 (Request Timeout) status code when a request takes more time to process than the server is willing to allot. 
This allows clients to distinguish timeouts from other failures and take an appropriate action.

Context

Emerged from pyvo discussion here:
astropy/pyvo#686

[mbtaylor]

This sounds like it should be a good idea and I was about to voice support for it, but if you look up the semantics of 408 it's actually not applicable for a timeout of server processing following a correctly submitted query. RFC 9110 sec 15.5.9 says:

The 408 (Request Timeout) status code indicates that the server did
not receive a complete request message within the time that it was
prepared to wait.

Is there a suitable HTTP response code for server timeout? Looking through RFC9110 and following a quick stackoverflow search I don't see anything better than 500 which I guess is what people are mostly doing already. Unless I'm missing something, the best option in compliance with standards is just a 500 or similar with an informative plain-text error message ("query timed out, try async instead"), in the expectation/hope that clients will pass this text on to the user - which I'd argue is a reasonable user experience in most cases.

Of course DALI could recommend to abuse 408 for the purpose of communicating a server timeout, but I'd feel a bit uncomfortable about that.

[msdemlei]

On Thu, Jul 10, 2025 at 02:09:01AM -0700, Mark Taylor wrote: mbtaylor left a comment (ivoa-std/DALI#62) This sounds like it should be a good idea and I was about to voice support for it, but if you look up the semantics of 408 it's actually not applicable for a timeout of server processing following a correctly submitted query. [RFC 9110 sec

Oh, that's too bad. Ah well: Si tacuisses. Me, in this case.

Is there a suitable HTTP response code for server timeout? Looking through RFC9110 and following a quick stackoverflow search I don't see anything better than 500 which I guess is what people are mostly doing already. Unless I'm missing something, the best

Odd, isn't it? You should think wanting to say "you wanted more resources than I was willing to give you" should be a rather normal use case. But right, the 4xx code should have warned me: what we want is some code in the 5xx range. And odd that there's just six 5xx-s.

option in compliance with standards is just a 500 or similar with an informative plain-text error message ("query timed out, try async instead"), in the expectation/hope that clients will pass this text on to the user - which I'd argue is a reasonable user experience in most cases.

Hmha. I like machine readability for things like these. Granted, a machine switching to async automatically when it got a timeout *is* a scary proposition, but still I don't think it's unreasonable to want to react to timeouts differently from your average "server broken".

Of course DALI *could* recommend to abuse 408 for the purpose of communicating a server timeout, but I'd feel a bit uncomfortable about that.

I agree that would be ghastly. So, what about carefully extending what QUERY_STATUS to allow a value of "TIMEOUT"? It's *almost* breaking, but I'd expect the typical client will already so something useful (presumably an error "unknown query status: TIMEOUT", which looks like a reasonable user experience to me). And future clients have a machine readable way to figure out they've been asking too much. Oh, and we perhaps should use a better word than TIMEOUT, because that could also happen while idling. Perhaps TIME_LIMIT_EXCEEDED? And once we have that: would we want machine-readable timeout signalling an async as well?

[stvoutsin]

Thanks for the feedback!

In light of @mbtaylor's concerns I agree about not abusing HTTP 408 and @msdemlei's direction toward extending QUERY_STATUS.

Thinking about this a bit more, I wonder if we can use QUERY_STATUS but in a slightly different approach that might be even better for long-term extensibility.

So rather than adding new QUERY_STATUS values like TIME_LIMIT_EXCEEDED, what if we keep QUERY_STATUS simple and add a structured error classification system alongside it?

Something like:

<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>

One key advantage I see to this is backward compatibility.
Existing clients that just check for QUERY_STATUS="ERROR" continue to work without any changes, whereas modern clients can choose to opt for more complex error handling and recommendations based on the ERROR_TYPE and ERROR_SUBTYPE.
This also scales better if we decide in the future to handle other error types (storage limits, authentication issues, query complexity, etc.).

So instead of adding additional QUERY_STATUS values, we get logical groupings:

ERROR_TYPE="RESOURCE_LIMIT" with subtypes TIME_LIMIT_EXCEEDED, STORAGE_LIMIT_EXCEEDED, etc.
ERROR_TYPE="AUTHORIZATION" with subtypes AUTHENTICATION_EXPIRED, INSUFFICIENT_PERMISSIONS, etc.
ERROR_TYPE="QUERY_SYNTAX" with subtypes INVALID_ADQL, TABLE_NOT_FOUND, etc.

If the subtyping is too complex perhaps we could also just have an ERROR_TYPE.

Bonus:

What if we also allowed providers to include additional metadata here about what happened and what the service capabilities/recommendations are:

<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"/>
    <INFO name="RECOMMENDED_ACTION" value="USE_ASYNC"/>
    <INFO name="SYNC_LIMIT_SECONDS" value="30"/>
    <INFO name="ASYNC_LIMIT_SECONDS" value="3600"/>
  </RESOURCE>
</VOTABLE>

RECOMMENDED_ACTION here could be useful to give an "actionable" recommendation to clients in case we want to enable automated client behaviour.

Other examples could be for example:

<INFO name="ERROR_SUBTYPE" value="TIME_LIMIT_EXCEEDED"/>
<INFO name="RECOMMENDED_ACTION" value="USE_ASYNC"/>

<INFO name="ERROR_SUBTYPE" value="RESULT_TOO_LARGE"/>
<INFO name="RECOMMENDED_ACTION" value="ADD_MAXREC"/>

<INFO name="ERROR_SUBTYPE" value="STORAGE_LIMIT_EXCEEDED"/>
<INFO name="RECOMMENDED_ACTION" value="REDUCE_RESULT_SIZE"/>

An automated response to ADD_MAXREC could be for the client to add MAXREC and retry.
Obviously many (most?) clients may make the UX design choice to just show the user an error message and let them choose their course of action, but at least something like this opens the door for clients choose if they want to add support for automated follow-up actions.

Any thoughts on these ideas?

[mbtaylor]

@msdemlei wrote

So, what about carefully extending what QUERY_STATUS to allow a value
of "TIMEOUT"? It's almost breaking, but I'd expect the typical
client will already so something useful (presumably an error "unknown
query status: TIMEOUT", which looks like a reasonable user experience
to me).

As it happens topcat confronted with a non-standard QUERY_STATUS (not OK, ERROR or OVERFLOW) would currently just ignore it (treating the result as otherwise successful) though I admit that's maybe something I should do differently with an eye to future standards evolution.

But that makes @stvoutsin's idea look good. I feel like more than one level of additional detail may not be worth the standardisation effort, but at the worst it would be harmless.

[msdemlei]

On Thu, Jul 10, 2025 at 10:11:31AM -0700, stvoutsin wrote: stvoutsin left a comment (ivoa-std/DALI#62) So rather than adding new QUERY_STATUS values like `TIME_LIMIT_EXCEEDED`, what if we keep `QUERY_STATUS` simple and So instead of adding additional `QUERY_STATUS` values, we get logical groupings: ``` ERROR_TYPE="RESOURCE_LIMIT" with subtypes TIME_LIMIT_EXCEEDED, STORAGE_LIMIT_EXCEEDED, etc. ERROR_TYPE="AUTHORIZATION" with subtypes AUTHENTICATION_EXPIRED, INSUFFICIENT_PERMISSIONS, etc. ERROR_TYPE="QUERY_SYNTAX" with subtypes INVALID_ADQL, TABLE_NOT_FOUND, etc. ```

That sounds good to me, too. I also like it because the list of terms seems like a natural case for a vocabulary, where clients can look up explanations and more general terms they might understand in there. Would you go to the DAL mailing list with this? If there is no major pushback there, I'd say we can go along with that (except I'd much better like lowercase and dashes at least in the values, but that's bikeshedding) in DaCHS, Rubin, pyVO, and perhaps TOPCAT, and write it up for DALI (1.2 or 1.3, whatever).

What if we also allowed providers to include additional metadata here about what happened and what the service capabilities/recommendations are:

Ummmm :-). I'd need a bit more convincing for the concept of machine-readable remedy recommendations. My hunch on that is that debugging/general error recovery is something that's too hard for two (or more) machines to work out between themselves (exhibit A: ***@***.***/112963396298364233).

[stvoutsin]

Yes happy to write up a message to DAL mailing list with this.
I don't really feel strongly enough about standardizing on prescriptive remedy recommendations so I will back-off on that one.
The motivation for something like SYNC_LIMIT_SECONDS was to allow clients/services the capability to act automatically on the failures, or provide more meaningful messages.

So something like:

<INFO name="ERROR_TYPE" value="RESOURCE_LIMIT"/>
<INFO name="ERROR_SUBTYPE" value="TIME_LIMIT_EXCEEDED"/>
<INFO name="SYNC_LIMIT_SECONDS" value="30"/>
<INFO name="ASYNC_LIMIT_SECONDS" value="3600"/>

Gives the client enough information where if it wishes it can add more sophisticated automation (retry, caching characteristics like what mode it should use between async/sync) etc..
So generally I feel like there would be a stronger case for descriptive metadata here rather than remedies.

Having said that, this may be prematurely optimizing for something that may not be needed, so I'm happy to leave this as a vague idea and focus on what is probably the easier thing to agree on which is a standard language for errors.