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-OriginFix
As above, or call from your server
A CORS error from a page opened from disk
Cause
The browser sends
null as the originFix
Serve the page, such as with
python3 -m http.serverBooking 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 serviceFix
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 onesThat 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
/slotsThat 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 bothA 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 itAnswer ‘<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 holdFix
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 falseFix
Only offer the waitlist when it is
trueThe 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 toFix
Send
YYYY-MM-DD days, at most 90 apart, not in the pastChanging 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
manageUrlIt'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 phoneThis 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 zoneFix
Send the visitor's time zone,
Intl.DateTimeFormat().resolvedOptions().timeZoneThe appointment's own time is missing when moving it
Cause
GET
/slots without manageFix
Send its manage token as
manage/staff is emptyCause
The location doesn't let customers choose a person
Fix
Leave out the person step. Booking Orbit picks someone.
Every price is
hiddenCause
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: falseCause
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 addressnpm install @bifrost-orbit-booking/sdk fails with 404Cause
The SDK is not on npm yet
Fix
Call the public booking API with
fetch for nowWas this page helpful?
Read next
Public booking APIEvery endpoint of the public booking API, with its parameters, answers and errors, and how access from browsers, rate limits, caching and paused locations work.Booking SDKThe JavaScript and TypeScript SDK for building booking screens in your own design, in the browser, on Node.js and at the edge, with every method, type and error.Allowed websitesWhy the public booking API needs no key, how allowed websites decide which browsers may book, and how to add your website, staging sites and local development.Embed the booking widgetShow Booking Orbit's booking screens inside a page of your website or in a popup, with one script tag, and open it from your own code.