Opened 9 years ago

Closed 9 years ago

Last modified 9 years ago

#2544 closed enhancement (wontfix)

Please document 412 error messages in detail

Reported by: matthias@… Owned by: tom@…
Priority: major Milestone: OSM 0.6
Component: api Version:
Keywords: Cc:

Description

The API documentation (http://wiki.openstreetmap.org/wiki/API_v0.6) explains what a 412 error is. It would be very helpful if all possible error strings were documented.

Even better would be if information about errors was returned in a structured form on top of the plain text to make automatic parsing easier.

Change History (8)

comment:1 Changed 9 years ago by TomH

  • Resolution set to wontfix
  • Status changed from new to closed

It's a wiki - feel free to document whatever you like.

comment:2 Changed 9 years ago by matthias@…

Well, I was hoping someone with some knowledge about the implementation could do that.

comment:3 follow-up: Changed 9 years ago by TomH

There is nobody with a list of the possible errors in their head whoever does it would have to search through the source code for error messages.

Listing possible error messages on the wiki is pretty much pointless anyway - it will just suffer from bitrot and will always be out of date and wrong with respect to the code. I'm not sure it would even be possible to find them all anyway as many will just be propagated from the XML parser and suchlike.

If you really want to do it then http://trac.openstreetmap.org/browser/sites/rails_port/lib/osm.rb is the place to start - the classes derived from APIError should cover most of the errors though I can't guarantee there aren't still some being output directly.

comment:4 Changed 9 years ago by TomH

By the way I assume you are aware of the Error header in API responses, which contains a textual description of the error?

comment:5 in reply to: ↑ 3 Changed 9 years ago by matthias@…

Replying to TomH:

Listing possible error messages on the wiki is pretty much pointless anyway - it will just suffer from bitrot and will always be out of date and wrong with respect to the code. I'm not sure it would even be possible to find them all anyway as many will just be propagated from the XML parser and suchlike.

That's unfortunate. What I am trying to do is to improve the handling of such errors in JOSM. This is basically impossible if the error strings change now and then. Apart from giving the general advice "If you get an error 412 try to update your data".

If you really want to do it then http://trac.openstreetmap.org/browser/sites/rails_port/lib/osm.rb is the place to start - the classes derived from APIError should cover most of the errors though I can't guarantee there aren't still some being output directly.

Thanks for that pointer.

And yes, I know about the error header. At least in the cases I have seen it contains the same text as the body.

Ideally the API would return some meta data (like id and type of the offending object) in a form that is better machine readable and less likely to change.

comment:6 follow-up: Changed 9 years ago by TomH

If you want the text so you can match it in the client then you're doing it wrong! The correct way to solve that problem, as you say, is to return structured information in the error not to start trying to decode the error messages.

Patches to add structured error messages are, as always, welcome.

comment:7 in reply to: ↑ 6 Changed 9 years ago by matthias@…

Replying to TomH:

If you want the text so you can match it in the client then you're doing it wrong! The correct way to solve that problem, as you say, is to return structured information in the error not to start trying to decode the error messages.

I know it's a crutch.

"grep -r APIPreconditionFailedError *" has turned up some results I will include in the wiki for now.

Patches to add structured error messages are, as always, welcome.

I thought so ;-)

I am neither a HTTP nor a ruby expert. So I don't know whether I will get around to provide that patch myself. Also, I don't feel like setting up a test server to try that stuff out.

Anyway, in which form do you think that information should be transmitted? I can think of a few possibilities:

  • in the Error header:
    Error: type=missing_element element=node12345,node67890 parent=way8765
    
  • in home-made HTTP headers:
    X-Error-Type: missing_element
    X-Error-Element: node 12345,node 67890
    X-Error-Parent: way 8765
    
  • in pseudo headers in the body:
    Way 8765 requires the nodes with id in (12345,67890), which either do not exist, or are not visible.
    
    =====
    Error-Type: missing_element
    Error-Element: node 12345, node 67890
    Error-Parent: way 8765
    

comment:8 Changed 9 years ago by tom@…

Well I would say we can't change the Error header as client will be displaying that to users.

I was assuming something like an XML body - the only concern then is whether clients are displaying the body to the users. To be honest I hadn't realised we included the error text in the body as I thought it was only in the Error header.

I would suggest discussing it on the dev list to see what people think.

Note: See TracTickets for help on using tickets.