Improve on error handling

[timvandenberg-sqills]

Placeholder to discuss the error handling in OSDM.

Example:

• CONFIRMATION_BOOKING_ALREADY_CONFIRMED and BOOKING_BOOKING_ALREADY_CONFIRMED, BOOKING_BOOKING_ALREADY_CANCELLED and CONFIRMATION_BOOKING_ALREADY_CANCELLED, probably better to rewrite to ALREADY_CONFIRMED and ALREADY_CANCELLED (since this addresses the same state of the booking)
• Basically try to create a minimal amount of context related messages

Start using the code field in 3.1, with a URN, where:

• default generic OSDM warnings and errors can be returned
• operator specific error codes can be returned

Improve on the documented values of the response HTTP status codes:

• Some messages can be returned as a warning or an error as well, resulting in a 200 HTTP response for the warning, a 400 HTTP response for the error

• Add on not yet documented errors and warnings (continuing process)

• Improve documentation

[schlpbch]

Decision: We setup small group to refine the situation lead by @timvandenberg-sqills

[jspetrak]

To implement the updated error handling, error detail object will adhere to updated RFC see #361

[schlpbch]

Presentation and approving on 2024-06-14.

[ralfbayer-db]

Regarding the documentation changes in branch feature/gh-pages-390, we suggest some additions

• There is no suitable problem code for http codes 401 and 503. Suggestion:

  • For 401, do not send a body (on auth. failures, security best practice suggests no further details to avoid giving an attacker any hints)
  • For 503, add a problem code "SERVICE_UNAVAILABLE", and the detail could add more information which service is not available at the moment, and possibly when the provider expects the service to be available again

• Add http code 429 without a body, to indicate to the consumer that they should stop flooding the system.

[ralfbayer-db]

Need to add 429 to the OpenAPI specification

[ralfbayer-db]

We have an inconsistency here: the documentation in https://osdm.io/spec/errors-problems/ specifies that http code 405 should be used. The OpenAPI / YAML specification states http code 406 instead.

We need to define which way we will move this and make it consistent.

[ralfbayer-db]

• 405 and 406 would both be generated by the overall framework, not by the API or its implementation
• therefore 406 should be removed from the YAML in 4.x (#675)
• 405 and 406 should be mentioned in the documentation, but it should be noted which http codes would typically be generated by the framework / server and therefore will not contain the problem payload.