# 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.

Source: https://docs.bifrostorbit.com/booking/developers/troubleshooting/

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

| Message or status | Cause | Fix |
| --- | --- | --- |
| `This website isn't allowed to book here. Add it to the allowed websites in Booking Orbit's settings.` (403) | A hold, booking or appointment change from a browser on a website that isn't allowed | 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 | The same, seen from the browser: the preflight gets no `Access-Control-Allow-Origin` | As above, or call from your server |
| A CORS error from a page opened from disk | The browser sends `null` as the origin | Serve the page, such as with `python3 -m http.server` |
| `Booking page was not found` (404) | The location's short name is wrong, the location was deleted, or an admin changed its short name | 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`) | The organisation's plan ended. Reading still works. | 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`) | Too many calls from one address. All calls from your server share its address. | Cache reads on your server, and hold and book from visitors' browsers. See the rate limits in the [public booking API](https://docs.bifrostorbit.com/booking/developers/public-api/). |

## Free times and holds

| Message | Cause | Fix |
| --- | --- | --- |
| `Name the service with ?service=` (400) | `GET /slots` without `service` | Send the service's id or short name |
| `Service was not found` (404) | A wrong id or short name, or a service that is **Team only** or was deleted | Read `GET /services` for the current ones |
| `That time is already taken` (409) | Someone else booked or held it a moment ago | 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) | The time isn't one of the free times, such as a time you built yourself | Only offer times from `GET /slots` |
| `That is too soon to book`, `That is too far ahead to book` (409) | The location's notice or how far ahead it takes bookings | 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) | The time filled up since you read it | Load the free times again |

## Booking

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

## Changing an appointment

| Message | Cause | Fix |
| --- | --- | --- |
| `Appointment was not found` (404) | A wrong or cut-off manage token, or a token for another location | 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) | It starts sooner than the location allows changes, often 24 hours | Check `canChange` before offering the buttons, and show the location's phone |
| `This appointment is already over or cancelled` (409) | Cancelling twice, or a past appointment | Read it again with `GET /manage/<token>` |
| `Only upcoming appointments can be moved` (409) | Moving a past or cancelled appointment | As above |

## Symptoms

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