Booking engine API error handling: three failures that cost money

The support ticket arrives on a Thursday evening. A customer paid, the page spun, then showed a generic error. The card was charged. Your logs show a POST to the supplier that never got a response. Did the airline hold a seat? Nobody can tell you, and the customer is waiting. Good booking engine API error handling is mostly the work of never being in that position, or at least knowing exactly what to do when you are.
Most integration guides treat errors as a catalogue of status codes. In booking, the codes are the easy part. What costs money is a small set of situations where the request looks like it failed but the world changed anyway, or looks like it worked and the world did not. Three of them matter more than the rest.
Failure one: the price moved between search and book
Search results are a quote, not a contract. Fares are cached, inventory is shared across every channel the supplier sells through, and the number you showed at 14:02 may be stale a few minutes later. The supplier tells you at the create-booking step, sometimes with a clean "fare changed" response, sometimes by quietly returning a different total inside an otherwise successful response.
The second variety is the dangerous one. If your code reads the confirmation, stores the booking and charges the customer the amount they saw, the difference comes out of your margin, or later out of an ADM. So the rule is simple: compare the total the supplier confirms with the total the customer accepted, every time, in code, before you capture payment.
What to do when they differ depends on the size of the gap and on who carries it. A few cents of rounding between currencies is a tolerance you set once. Anything larger goes back to the customer as a new price with an explicit accept button. Never auto-absorb it, and never auto-charge it.
Failure two: booked, but not ticketed
A PNR existing is not the same as a ticket existing. Many flows create the reservation first and issue the e-ticket as a separate step, with a time limit between them. If payment succeeds and issuance fails, you are holding a customer's money and a reservation that will expire on its own clock.
The failure is rarely loud. The issue call returns an error, or a timeout, and the booking sits in a state your database labels "paid" while the supplier still says "held". Meanwhile the ticketing time limit is running, and unlike your support queue, the airline does not wait.
Handle it as its own state, not as a variant of success or failure. A booking needs at least these: created, held, payment captured, issuing, ticketed, failed-and-refundable. "Payment captured, issuing" is the state that needs a timer: when a booking has sat there too long, a job should re-read the reservation from the supplier and decide, not wait for a human to notice. The decision is cheap when you know the supplier's time limit, because it tells you how long you can safely retry before you have to refund.
Failure three: the timeout with an unknown outcome
This is the Thursday evening ticket. Your request left; no response came back; the connection died or the gateway gave up. The supplier may have processed it fully, partly, or not at all.
The temptation is to retry. Do not retry a create-booking call blindly, because the second attempt can produce a second reservation, and a duplicate is a real cost: two seats held, perhaps two tickets issued, a refund fight on one of them.
The safe order is: stop, then read, then decide. Stop the customer-facing flow with an honest "we are confirming your booking" state. Read the supplier's side by looking up the booking using the reference you generated before the call (this is why you create your own client reference first, and send it along if the supplier accepts one). Only then decide: found means continue from the real state; not found after the supplier's own processing window means it is safe to retry once.
If the supplier gives you no way to look up by your reference, search by passenger name, route and date within a narrow window, and treat a match as found. Ugly, but far cheaper than a duplicate.
A decision table you can disagree with
| What you see | What you know | What to do | What not to do |
|---|---|---|---|
| Supplier returns "fare changed" | Nothing was booked | Show the new total, ask for acceptance, re-run create | Re-run with the old price and hope it passes |
| Success, but total differs from what the customer accepted | A booking exists at the new price | Hold the payment, ask the customer, void the booking if they decline | Capture the old amount and eat the difference |
| Payment captured, issue call errors | A PNR exists, ticket status unknown | Re-read the reservation, retry issue within the time limit, refund after it | Mark the booking failed and forget the PNR |
| Timeout on create | Outcome unknown | Look up by your reference, then continue or retry once | Immediate blind retry |
| Timeout on cancel | You may still be liable for the segment | Re-read the status before telling the customer anything | Show "cancelled" because the click happened |
One row you may dispute: some teams refund at the first issuance error to keep the customer calm. That is defensible for small tickets and a bad habit for expensive ones, since you can lose a fare you could have saved a minute later.
What it costs you to get this wrong
Each failure has a different bill. A missed price change is margin lost on every booking it touches, often unnoticed until reconciliation. A booked-not-ticketed case is a customer who arrives at the airport with a reservation that lapsed and a charge on their card, which is a chargeback and a reputation problem at once. A blind retry on timeout is a duplicate reservation, and airlines audit duplicates; a pattern of them is the sort of thing that ends up in an ADM.
None of this is exotic. It is the unglamorous plumbing that separates a demo from something you can leave running over a weekend.
Build the reconciliation job before you need it
All three failures end the same way: your database and the supplier's disagree. So write the job that compares them before the first incident, not after. A nightly run is the minimum; every few minutes for anything in a transitional state is better. It lists bookings stuck in held, issuing or unknown, asks the supplier what it thinks, and either repairs the record or raises a ticket with the evidence attached.
Keep every request and response for booking calls, including timeouts, with the reference you sent. When a customer disputes a charge, that log is the argument. It also keeps the latency conversation honest: see what you can and cannot fix about API latency for why timeouts are a fact of life rather than a bug to eliminate.
If you are still deciding how to wire the supplier connection itself, the walkthrough in flight booking API integration covers the order of calls this article assumes. And if you want to talk through how these states map onto our flight and hotel APIs, access starts as a conversation: see the travel API page.