Outcomes & retries

There is no undo

No supplier in the GoHub estate exposes an agent cancel. A confirmed booking stands until operations reconcile it by hand. Everything on this page exists to keep you from booking twice.

The three outcomes

Status	Order state	What happened	What to do
201	CONFIRMED	Booked at the supplier. The artifact exists.	Deliver it.
422	FAILED	The supplier declined. Nothing charged, anything partial compensated.	Re-quote, then try again.
409	—	Either the quote expired, or the outcome is not yet known.	Read the body.

201 and 422 are both final and both safe. The care is all in 409.

Reading a 409

Three different situations share this status, and they want opposite responses:

Expired quote — the price window closed before you booked. Get a new quote. A retry with the same one will keep failing.

RECONCILING — the supplier gave no definitive answer (a timeout, a 5xx), so the engine does not yet know whether the booking exists. It is resolving it.

Re-send this exact request with the same idempotencyKey until you get 201 or 422, or poll GET /api/v1/bookings/{id}.

Booking again with a fresh key here is the one genuinely dangerous move in this API: it risks a second real, uncancellable booking. The same key cannot do that — it replays the original order.

insufficient-funds — a PREPAID agent below its floor. Deterministic and safe: nothing was booked. The body carries the numbers you need:

{
  "status": 409,
  "detail": "Agent 42 cannot fund payable 77.00 (balance 20.00, held 0.00, credit limit 0.00)",
  "reason": "insufficient-funds",
  "balance": 20.00, "held": 0.00, "creditLimit": 0.00, "payable": 77.00
}

Idempotency, concretely

Generate one key per booking attempt — a UUID is ideal — and persist it alongside your own order record before you call. Then:

• Timeout or connection error? Re-send with the same key. Either it books, or you learn it already did.
• 409 RECONCILING? Same key, again, until it resolves.
• Customer changes their mind before you got a 201? Still finish the retry loop and find out what happened. An order you abandoned mid-flight may well have booked.

A new key is only ever correct for a genuinely new booking.

Item states inside a confirmed order

A multi-leg order can hold legs in different states while compensation runs. The ones worth handling:

items[].state	Meaning
CONFIRMED	Booked at the supplier.
FAILED	Not booked. Nothing charged for this leg.
UNKNOWN	Ambiguous — we do not know whether the supplier booking exists. Awaiting reconciliation.
FULFILLED / NO_SHOW	Post-trip outcomes, where the supplier reports them.

warning

Never retry an UNKNOWN leg yourself. It is precisely the case where a retry books twice.