[OSM-dev] Overpass-API error codes

[Roland Olbricht]

Am Freitag, 30. März 2012 11:15:26 schrieb Peter Wendorff:
> Hi.
> In a software I'm going to use the Overpass-API to fetch OSM-Data, and I
> think about handling error codes.
> As far as I see, Overpass prints errors in a <remark>-Tag in human
> readable text, but nowwhere as machine-readable text, while most error
> codes I guess could be mapped on HTTP-response states.

Well, I'm not sure whether HTTP-response codes are here the best way to encode 
error states. The by far most important error situations are
1. A timeout on the server
   The client shouldn't use the result, as it may be incomplete. It can retry
   with a longer timeout.
2. Connection refused
   This would happen in case of overload, does happen rarely at the moment,
   but it should be addressed by a client. The client should retry after a
   timespan of 1 to 5 seconds again.
3. A malformed request
   It would be unusual if this happens when the request is generated
   programmatically. If a human user has entered the query, the client should
   pass the HTML document to the human user.

The more simpler approach would be to process the result if it is OSM XML and 
to pass it to the end user if it is HTML.

Specifically the first one cannot be handled by a HTTP status code. The status 
code is always the first thing to be written. Thus, to send a different HTTP 
status code in case of a timeout, the servers needs to held back the payload 
until the request has been completed. That impedes a couple of use cases where 
the client could take advantage of early arriving responses. Thus, a response 
started with HTTP 200 may still fail later with a timeout.

Thus, in the end a client (think of a JavaScript framework would need to 
handle both some kind of errors coming from HTTP status codes and timeouts 
which cannot appear anyway else than as tags in the already started document.
 
> Is it planned (or a good idea that's planned now ;) ) to add a machine
> readable error state somehow?
> this could be done e.g. by adding a error-code attribute to the
> remark-attribute.

What do you think about a switch to enforce XML as output format and
<error what="timeout"/>
<error what="overload"/>
<error what="bad_request"/>
as error indication?

This would allow to ignore all <remark/> tags in case you want to reliably 
respond to fatal errors and to ignore the rather diagnostic information. If 
somebody needs error details, he or she can read the messages in the remark-
tags or resend the query to get a HTML explaining the error.

Best regards,

Roland