Handle timeouts and retries

Reads are safe to retry. Bookings and cancellations are not, because the PMS may have acted even when you didn't get the response.

Retry reads with backoff

Retry these requests after a network failure or a 5xx, with bounded exponential backoff and jitter:

• List listings, Get a listing, and List units
• Search and Search by IDs
• Get availability
• Create a quote. A quote books nothing.
• Get a reservation

Don't retry 4xx responses unchanged. Fix the request first.

Never retry a reservation blindly

Reservation creation is not idempotent. OnSeason doesn't accept an Idempotency-Key header, and a quoteToken is not an idempotency key. If you send the same reservation twice, you can get two bookings.

If POST /api/v1/reservation times out or the connection drops:

1. Don't send the request again.
2. Contact OnSeason support with the request time in UTC, the listing ID, the guest's last name, and the stay dates. Support finds the booking if it exists.
3. If the booking doesn't exist and the quote has expired in the meantime, quote again before you book.

If the response is 422 with the message Your reservation may have been created — please contact support, reference: …, the PMS accepted the booking but OnSeason couldn't finish recording it. Don't book again. Send the reference to support.

Check before you retry a cancellation

If DELETE /api/v1/reservation/{id} times out, get the reservation and read status before you do anything else:

• CONFIRMED: the cancellation didn't happen. Send it again.
• CANCELLED or CANCELLATION_PENDING: the cancellation went through. Read cancellationCharge from the reservation.

Keep your own booking map

The API has no field for your booking reference. Keep this mapping in your system for every booking:

Send the same source value on every reservation. It names your channel but is not unique per booking.

Keep load predictable

OnSeason doesn't publish a fixed rate limit or a Retry-After contract yet. Agree expected traffic, concurrency, and load tests with OnSeason before launch. In the meantime:

• Page through large result sets instead of asking for everything at once.
• Cache property content and refresh it from updatedAt.
• Quote only when a booking is close.
• Back off with jitter on 5xx and network errors.
• Stop retrying when a PMS is degraded, so retries don't pile up.