Release of structured errors for bookings
Starting from today our retrieve booking endpoint will populate a new errors field for each reservation.
Introduction
The field contains structured errors regarding the confirmation of bookings.
Since our confirmation flow is asynchronous, the field is populated after we have have sent the booking to the supplier's system.
You can use the new field to determine the reason for:
- Confirmation failures
- Cancellation failures
The errors will help you:
- Understand why a confirmation failed without having to reach our support
- Handle failures in a graceful way and have a better way to present the failures to your users
- Fix issues that might be causing the failures on your part
Failure codes and explanation
| Code | Explanation |
|---|---|
| NO_AVAILABILITY | The supplier reported that the requested inventory was no longer available at booking time. The rate was available when quoted but sold out before the booking was confirmed. |
| PRICE_CHANGED | The supplier returned a different price at booking time than the one that was quoted. The booking was not created at the new price. |
| EXTERNAL_TIMEOUT | The supplier did not respond to the booking request within the allowed time. The booking status on the supplier side is unknown. |
| PAYMENT_ERROR | There was an issue with the payment card used for the booking (e.g. supplier could not charge the card because of insufficient funds) |
| SUPPLIER_ERROR | The supplier rejected the booking for a reason not covered by the more specific codes above. This is the fallback for supplier-side failures and may include validation errors returned verbatim by the supplier. |
| INTERNAL_SERVER_ERROR | The failure occurred within Katanox rather than at the supplier. No supplier error is implied. Retrying the request may succeed. |
| CANCELLATION_REJECTED | We tried to cancel the booking, but the supplier either rejected the cancellation (due to the booking not being cancellable anymore) or their system did not respond in time |
Handling errors
How to handle errors
All values except INTERNAL_SERVER_ERROR describe a failure on the supplier's side.
Together with the code, you will also get a message explaining the failure. Sometimes the same error code may have different causes and thus different messages.
An example of this is the SUPPLIER_ERROR which returns errors from the supplier directly. This can be one of:
- validation errors of the supplier themselves
- an internal issue of the supplier's system
In that case we suggest that you look into the message to better understand the reason for the code.
Retries
As previously mentioned, the error code is populated only after we have sent the request to the supplier. This means that booking operations cannot be retried and cancellation operations may be retried depending on the error itself.
When the error occurs after you attempt to create the booking, you cannot retry because the offer you used has been invalidated by performing the operation. That means you have to create a new booking which may or may not pass depending on the error.
For example, if you create a booking and you receive a SUPPLIER_ERROR with a message customers first name must be less than 10 characters any new booking attempts will also fail unless you pass a smaller name.
Similarly for cancellations: if you try to cancel and get a timeout error, you can retry the same operation, but the cancellation may still fail if the supplier has an outage, for example.
On the other hand, if the cancellation is rejected because the cancellation policy is now active the cancellation will not succeed no matter how many times you try.