Skip to content

Troubleshooting for developers

The error messages the public booking API, the Booking SDK and the widget give, and common symptoms, each with the cause and the fix.

Reference6 min read

Find the message or symptom, then the cause and the fix. Every API error is JSON: { "error": { "code": "…", "message": "…" } }. Messages are in English and fine to show to a customer. The SDK throws them as a BookingError with the same status, code and message.

Access

This website isn't allowed to book here. Add it to the allowed websites in Booking Orbit's settings. (403)
Cause
A hold, booking or appointment change from a browser on a website that isn't allowed
Fix
Add the exact origin, such as https://northwilds.com, under Settings › Your website. https://www.northwilds.com and http://localhost:5173 are different origins.
A CORS error in the browser, with no answer
Cause
The same, seen from the browser: the preflight gets no Access-Control-Allow-Origin
Fix
As above, or call from your server
A CORS error from a page opened from disk
Cause
The browser sends null as the origin
Fix
Serve the page, such as with python3 -m http.server
Booking page was not found (404)
Cause
The location's short name is wrong, the location was deleted, or an admin changed its short name
Fix
Copy it again from the booking page address under Booking page
This location is paused because its Booking Orbit trial or plan has ended. … (402, subscription_inactive)
Cause
The organisation's plan ended. Reading still works.
Fix
Nothing to fix in the code: say online booking is unavailable for now. In the SDK, catch BookingPausedError.
Too many tries. Wait a minute and try again. (429, rate_limited)
Cause
Too many calls from one address. All calls from your server share its address.
Fix
Cache reads on your server, and hold and book from visitors' browsers. See the rate limits in the public booking API.

Free times and holds

Name the service with ?service= (400)
Cause
GET/slots without service
Fix
Send the service's id or short name
Service was not found (404)
Cause
A wrong id or short name, or a service that is Team only or was deleted
Fix
Read GET/services for the current ones
That time is already taken (409)
Cause
Someone else booked or held it a moment ago
Fix
Load the free times again. In the SDK, isTimeTaken(error) is true.
That time is outside working hours, The location or person is closed then (409)
Cause
The time isn't one of the free times, such as a time you built yourself
Fix
Only offer times from GET/slots
That is too soon to book, That is too far ahead to book (409)
Cause
The location's notice or how far ahead it takes bookings
Fix
Use GET/slots, which already follows both
A room or piece of equipment it needs is taken then, That session is full, That person has as many of these as they take in a day (409)
Cause
The time filled up since you read it
Fix
Load the free times again

Booking

Add your name, Enter a valid email address (422)
Cause
name is empty or email isn't an address. issues lists every field that failed.
Fix
Check the form before sending
Add a phone number (400)
Cause
The location asks for a phone number
Fix
Read bookingPage.phone from GET/ and ask for it
Answer ‘<question>’, Choose an answer for ‘<question>’, Tick ‘<question>’ to book (400)
Cause
A required question is missing, or a choice isn't one of the options
Fix
Build the form from GET/services/<service>. Send option ids, not labels.
The time you picked was held for 10 minutes and has run out. Pick a time again. (409)
Cause
The hold ran out, or was already used
Fix
Hold again, or ask the customer to pick a time again
The held time doesn't match. Pick a time again. (409)
Cause
startsAt or service differs from the hold
Fix
Send the same time and service you held
<Location> takes at most <n> bookings a day from one person (409)
Cause
The location limits bookings per customer per day
Fix
Tell the customer; nothing to retry
This location doesn't keep a waitlist. (403)
Cause
POST/waitlist when bookingPage.waitlist is false
Fix
Only offer the waitlist when it is true
The latest day must be on or after the earliest day, Choose a window of up to 90 days, Choose days that haven't passed (400)
Cause
The waitlist's from and to
Fix
Send YYYY-MM-DD days, at most 90 apart, not in the past

Changing an appointment

Appointment was not found (404)
Cause
A wrong or cut-off manage token, or a token for another location
Fix
Take the token from the end of manageUrl
It's too late to move this appointment online. … or It's too late to cancel this appointment online. … (403)
Cause
It starts sooner than the location allows changes, often 24 hours
Fix
Check canChange before offering the buttons, and show the location's phone
This appointment is already over or cancelled (409)
Cause
Cancelling twice, or a past appointment
Fix
Read it again with GET/manage/<token>
Only upcoming appointments can be moved (409)
Cause
Moving a past or cancelled appointment
Fix
As above

Symptoms

Free times are off by an hour or a day
Cause
No timeZone, so days follow the location's time zone
Fix
Send the visitor's time zone, Intl.DateTimeFormat().resolvedOptions().timeZone
The appointment's own time is missing when moving it
Cause
GET/slots without manage
Fix
Send its manage token as manage
/staff is empty
Cause
The location doesn't let customers choose a person
Fix
Leave out the person step. Booking Orbit picks someone.
Every price is hidden
Cause
The location hides prices on the booking page
Fix
Respect it, or show prices from your own content
This service is paid online when it's booked, so book it on the booking page. (409, payment_required)
Cause
The service asks for a deposit, the full price or a saved card online, which only the booking page and the widget take
Fix
Send the customer to bookingUrl from the answer, or use the widget. In the SDK, isPaymentRequired(error) is true.
A booking is pending with payment.required: false
Cause
The location confirms bookings itself (policies.requireApproval)
Fix
Tell the customer it waits for confirmation. They get an email either way.
A new service doesn't show for a minute
Cause
Reading answers may be cached for 60 seconds
Fix
Wait a minute
The widget is 480 pixels high and doesn't grow
Cause
A Content Security Policy blocks it, or the script loaded from a different address than the frame
Fix
Allow https://app.bifrostorbit.com in script-src and frame-src, and load widget.js from the same Booking Orbit address
npm install @bifrost-orbit-booking/sdk fails with 404
Cause
The SDK is not on npm yet
Fix
Call the public booking API with fetch for now

Was this page helpful?

Read next