Red toasts carry the server's exact message; the status code tells you which kind of problem it is.
- 400 Bad request: the form has a value the server will not accept. Fix the value and retry. Validation failures list the field and reason (“Validation failed”).
- 401 Unauthorised: the session is gone. The app refreshes it silently once; if that fails you land on sign-in.
- 403 Forbidden: your role may not do this. Ask an administrator or a supervisor.
- 404 Not found: the record vanished (deleted, or another sandbox). Refresh the list.
- 409 Conflict: the action is not allowed from the record's current state, or another desk got there first. Read the message; refresh; act on the new state.
- 429 Too many requests: throttled. Wait the stated time.
- Offline / 502: nothing reached the API. See the Offline pill section below.
Bounced to sign-in, the access screen, login throttling, the Offline pill, the update banner and expired demos.
You were sent back to sign-in
Your access cookie lives 15 minutes and refreshes silently while you work; the refresh token lives 30 days. You are bounced when the refresh is refused: you signed out elsewhere, an administrator deactivated your account (This account has been deactivated), your password was changed (all sessions are revoked), or the refresh token expired. Sign in again. If the API was merely unreachable, the app keeps your cookies and treats it as offline instead.
“You don't have access to …”
A module page shows a lock and “Your role (Receptionist) isn't permitted to view this module” when your level for that module is None. User Roles needs Full on Settings; the Audit log is for Super Admin, Hotel Manager, Security or anyone with Settings Full. Role changes take effect within about 15 seconds without signing out. Contact your administrator if you need access.
Too many sign-in attempts (429)
Ten failed attempts for the same email (or the same hotel PIN) from your address within 15 minutes lock it out: Too many failed sign-in attempts. Try again in 15 minutes or Too many failed PIN attempts. Try again in 15 minutes. Password reset requests are limited to three per address per 15 minutes (Too many reset requests. Try again later). A successful sign-in clears the counter.
The Offline pill, or “Request failed (502)”
When the API cannot be reached, no network, or the proxy answers 502/503/504, the app raises an offline condition instead of an error. The top bar shows Offline; whitelisted front-desk actions queue, everything else shows “You appear to be offline” or “Could not load this page”. Check the connection and wait; the pill turns to Syncing and disappears by itself. If it stays grey while other sites work, the API is down, tell whoever runs the server. See the Offline chapter for the queue rules.
“A new version is available.”
A bar at the bottom means a new build was deployed and downloaded. Press Update to reload onto it (finish typing first, unsaved drawer edits are lost), or Later; the next full reload picks it up anyway.
Demo sandbox expired
Sandboxes live 24 hours. When yours is swept, the next request answers This demo has expired(401) and you land on the sign-in page; the chip may have read “Demo · expired” for a few minutes before. Pick a role again to get a fresh sandbox. If the host is busy you may see The demo is at capacity right now. Please try again in a little while (503) or You have started several demos recently. Try again in an hour (429, six starts per hour per address).
Messages from the login form, PIN pad, password reset and account settings.
401Invalid email or password
WhyNo active account with that email and password in a real (non-demo) hotel, or the account is deactivated.
FixCheck for typos and caps lock. Use Forgot password, or ask an administrator to check the account is active in Staff → Accounts.
409HOTEL_AMBIGUOUS
WhyThe same email and password are valid in more than one hotel on this host.
FixOpen the sign-in page from your hotel's own link so the form knows which hotel to use.
401Invalid PIN
WhyThe PIN does not match this hotel, the chosen person is not an active user, or that person is an admin-tier role (Super Admin, Hotel Manager, or anyone with Settings Full), which the PIN can never sign in as.
FixRe-enter the PIN. Managers must use email and password.
400Open the sign-in page from your hotel's link so the PIN pad knows which hotel to unlock
WhyMore than one hotel on this host uses that PIN and no hotel was named in the address.
FixUse the hotel-specific sign-in link.
429Too many failed sign-in attempts. Try again in 15 minutes
WhyTen failures for that email from your address within 15 minutes.
FixWait 15 minutes. A correct sign-in resets the counter.
429Too many failed PIN attempts. Try again in 15 minutes
WhyTen wrong PINs from your address within 15 minutes.
FixWait 15 minutes, then try again with the current PIN (Settings → Hotel shows who may change it).
429Too many reset requests. Try again later
WhyMore than three reset emails for one address in 15 minutes, or ten from one IP in an hour.
FixCheck the mailbox (and spam) for the earlier email before requesting another.
401Reset link is invalid or expired
WhyThe reset link was already used, was edited, or has timed out.
FixRequest a new reset link from the sign-in page.
401Current password is incorrect
WhySettings → Account → change password needs your current password and it did not match.
FixRe-type the current password; if you cannot remember it, sign out and use Forgot password.
401Session expired
WhyThe access cookie could not be verified and the silent refresh failed.
401This account has been deactivated
WhyAn administrator switched your account off; it takes effect everywhere within seconds.
FixSpeak to your administrator.
401Not authenticated
WhyA request reached the API with no session cookie at all (usually a bookmarked API link or a very old tab).
FixOpen the app normally and sign in.
401No refresh token
WhyThe refresh cookie is missing (cleared site data, different browser profile).
401Invalid refresh token
WhyThe refresh token was revoked (sign-out elsewhere, password change) or belongs to a deactivated user.
The one message the role guard sends when your level is too low for an action.
403Your role (Receptionist) has "View only" on Payments; this action needs "Can edit".
WhyEvery write names the module and level it requires (View, Can edit, Full access). Your role's level in User Roles is below it. The role, module and levels in the message vary.
FixAsk someone whose role has that level, or ask an administrator to raise your role's level in User Roles. Buttons you cannot use are normally hidden; you mostly see this after a role change mid-session.
Which module a screen counts under: Housekeeping and Maintenance are Rooms; POS, Restaurant and Inventory are Payments; User Roles, Settings and the Audit log are Settings.
New booking, dates, groups, rate plans, check-in, check-out, cancel and no-show.
400Check-out must be after check-in
WhySame-day or reversed dates on a booking or group.
FixSet check-out at least one night after check-in.
400Provide either guestId or a new guest
WhyThe wizard sent both an existing guest and a new guest, or neither.
FixPick a guest from the search or fill in the new-guest fields, not both.
400month must be YYYY-MM
WhyThe calendar view was opened with a malformed month in the address.
FixUse the calendar's own month arrows, or fix the URL to e.g. 2026-09.
400Room 204 is not a Deluxe
WhyA specific room was chosen whose type differs from the room type selected on the booking.
FixChange the room type to match, or pick a room of the booked type.
409Room 204 is out of service
WhyThe chosen room is flagged out of service (or “under maintenance”) and cannot be sold.
FixPick another room, or return the room to service from Rooms first.
409Room is already booked for those dates
WhyThe database's no-overlap guard refused: another active booking (new, confirmed or in-house) holds that room for an overlapping night. Same-day turnover is allowed; overlapping nights are not.
FixPick a different room or dates. Rooms → availability shows what is free. If this appears in the Offline tray, re-room the guest and check in again.
409No Deluxe left for 2026-09-12: 8 sellable, 8 already booked
WhyThe capacity guard: counting assigned and unassigned bookings of that type, one night in the range would exceed the sellable rooms (maintenance and out-of-service rooms do not count). Groups add “, 3 requested”.
FixChoose another room type, shorten the stay, or free a room (cancel, move, or return one to service).
409Cannot edit a checkedout booking
WhyChecked-out, cancelled and no-show bookings are closed history.
FixCreate a new booking instead. Money corrections go through the invoice.
409Room 204 is unavailable
WhyOn edit or check-in the room is out of service or under maintenance.
FixPick another room; return the room to service if it is ready.
409Cannot check in a cancelled booking
WhyOnly new or confirmed bookings can be checked in. The status in the message varies (checkedin, checkedout, noshow…).
FixFor a checked-in guest nothing is needed. For a cancelled booking, make a new one.
409BK-1042 arrives on 2026-09-06. Move the booking dates for an early check-in
WhyCheck-in is only allowed on or after the hotel-local arrival day so the folio charges the nights actually slept.
FixEdit the booking's check-in date to today first (subject to capacity), then check in.
400Assign a room before check-in
WhyThe booking has no room and none was chosen in the check-in dialog.
FixPick a ready room in the dialog.
400Room 305 is a Suite; BK-1042 was booked as a different type. Assign it on the booking first
WhyA room picked at the desk must match the booked type. Upgrades are deliberate: assign the room on the booking (edit) before check-in.
FixEither pick a room of the booked type, or edit the booking to assign the upgrade room, then check in.
409Room 204 is not clean yet (HK-88 is open). Pick another room or wait for housekeeping
WhyA room is sellable only after housekeeping releases it; an open task (dirty, assigned, in progress or inspection) blocks it.
FixChoose a ready room, or have housekeeping move the task to Ready.
409Room 204 is still occupied by BK-1031. Check them out first
WhySame-day turnover: the outgoing guest has not been checked out yet.
FixCheck the previous guest out, then check in.
409Cannot check out a confirmed booking
WhyOnly in-house (checked-in) bookings check out.
FixNothing to do for a booking that never arrived, cancel or mark no-show instead.
409UGX 240,000 outstanding. Collect it before check-out, or a Payments manager can check out and bill later
WhyThe folio still has a balance. Check-out requires a settled folio (code FOLIO_UNSETTLED).
FixRecord the payment in the drawer, or ask someone with Payments Full to check out with “settle later”.
403UGX 240,000 outstanding. Only Payments "Full access" can check out with a balance
Why“Settle later” was requested by a role below Payments Full.
FixA Payments manager must do this check-out; it is audited and the folio stays collectable.
400occurredAt must be within the last 48 hours
WhyA queued offline check-in or check-out replayed more than 48 hours after it was captured (or with a future time).
FixDismiss the row in the Offline tray and do the action again now.
409Cannot move a checkedin booking to cancelled
WhyStatus changes follow the lifecycle: confirm from new; cancel or no-show only before check-in.
FixAn in-house guest checks out; use the correct action for the current status.
400Cap a group at 80 rooms
WhyA group block asked for more than 80 rooms in total.
FixSplit it into two groups.
404Rate plan not found
WhyThe chosen rate plan was deleted or deactivated.
FixPick another plan or BAR.
400That rate plan does not apply to this room type
WhyThe plan is restricted to one room type.
FixChoose a plan for the selected type, or change the type.
400Rate plan WKND already exists
WhyRate-plan codes are unique per hotel.
404Booking not found
WhyThe booking was deleted or belongs to another hotel/sandbox.
Room and room-type setup, out of service, and the housekeeping board.
409Room 204 already exists
WhyRoom numbers are unique per hotel.
FixUse a different number, or edit the existing room.
409Room 204 has booking history. Mark it "Out of Service" instead of deleting
WhyRooms with bookings are kept for reporting.
FixUse Out of service on the room instead.
409Room type "Deluxe" already exists
WhyRoom-type names are unique per hotel.
FixPick another name or edit the existing type.
409"Deluxe" still has rooms or bookings attached
WhyA room type cannot be deleted while rooms or bookings reference it.
FixMove or delete its rooms first.
400to must be after from
WhyThe availability search has a reversed date range.
FixSet the to date after the from date.
409Cannot move from dirty to ready
WhyHousekeeping moves follow the board: Dirty → Assigned or In Progress; Assigned → In Progress (or back to Dirty); In Progress → Inspection (or Dirty); Inspection → Ready (or back to In Progress). Ready is final.
FixMove one column at a time in the allowed direction.
404Checklist item not found
WhyThe tick was sent for an item that no longer exists on this task.
404Task not found
WhyThe task was completed and archived, or belongs to another hotel.
Work-order transitions.
409Cannot move from reported to completed
WhyWork orders follow Reported → Assigned → In Progress ⇄ Waiting for Parts → Completed → Closed. Assigning a technician or picking External moves Reported to Assigned by itself.
FixMove one step at a time.
409Closed work orders cannot be reopened
FixRaise a new work order and reference the old code in the notes.
404Work order not found
WhyDeleted or in another hotel.
Guest profiles and exports.
404Guest not found
WhyThe guest chosen for a booking, group or edit no longer exists.
FixSearch again and pick the current record.
403Guest exports need Guests view access
WhyExporting the guest list requires at least View on Guests, on top of the Reports level.
FixAsk an administrator for Guests access, or have a colleague run the export.
Staff records, rota, attendance, leave, user accounts and roles.
400That account is already linked to a staff record
WhyA user account can be linked to one staff record only.
FixUnlink it from the other record first, or leave this record without a login.
400Start and end time must differ
WhyA shift template with equal start and end has no length. Overnight windows are fine (end before start).
FixSet a real window, e.g. 18:00 – 06:00.
400That record is retired, restore it before rostering shifts
WhyRetired staff cannot be rostered, marked present or booked on leave (the wording varies: “…before recording attendance”, “…before booking leave”).
FixRestore the record from the directory, then retry.
400Attendance cannot be recorded for a future date
WhyAttendance is a statement about a day that has happened.
FixRecord it on or after the day.
400End date must not precede start date
400A single request cannot span more than a year
WhyLeave requests are capped at a year.
400Overlaps LV-12 (pending) for the same staff member
WhyThe person already has a pending or approved request covering some of those days.
FixCancel or adjust the other request first.
400Only pending requests can be cancelled (this one is approved)
WhyApproved, rejected and cancelled requests are final for the requester (deciding likewise: “Only pending requests can be decided”).
FixAsk a Staff-Full user to handle an approved request by other means, e.g. a correcting request.
400Overlaps already-approved LV-9
WhyApproving this request would overlap an already-approved one.
FixReject it, or cancel the other request first.
409A user with that email already exists
WhyEmails are unique per hotel.
FixSearch Accounts for the existing user and edit it.
400You cannot deactivate or change the role of your own account
WhyProtects against locking yourself out.
FixAsk another administrator.
403Only a Super Admin can manage Hotel Manager accounts
WhyAdmin-tier accounts (Super Admin, Hotel Manager) can only be created or edited by a Super Admin.
409The Super Admin role is fixed at full access
WhyIts permission matrix cannot be edited.
FixCreate or edit another role.
409Full access on Settings is reserved for admin-tier roles (Super Admin, Hotel Manager); give Receptionist "Can edit" at most
WhySettings Full makes a role admin-tier (roles, users, the PIN), which the shared front-desk PIN must never reach.
FixSet Settings to Can edit or lower for non-admin roles.
403The audit log is limited to Super Admin, Hotel Manager and Security
WhyOnly admin-tier roles and Security read the audit trail.
FixAsk one of them for the entries you need.
Recording payments, refunds, emailing invoices.
400Amount must be positive
WhyA zero or negative payment amount.
FixEnter the amount received.
400Select the mobile money network
WhyMobile-money payments need MTN or Airtel.
409Invoice is already settled
WhyThe balance is zero (or the invoice is refunded); nothing to collect.
FixNothing to do. Over-payments are not accepted.
409Amount exceeds the outstanding balance (UGX 120,000)
WhyPart-payments are fine, but never more than what is owed.
FixEnter at most the stated balance.
409That entry is itself a refund
WhyYou tried to refund a refund line.
FixRefund the original payment (PAY- code) instead.
409PAY-311 has already been refunded in full
WhyEvery refund is capped by the original payment; this one has nothing left.
FixNothing to refund on that payment.
400Refund must be positive
WhyZero or negative refund amount.
FixEnter the amount, or leave it blank to refund what is left on the payment.
409Refund exceeds what is left on PAY-311 (UGX 50,000 refundable)
WhyRefunds on one payment cannot add up to more than it.
FixRefund at most the stated amount.
409Refund exceeds the amount received on this invoice
WhyNet cash on the invoice would go negative.
400Guest has no email address
WhyEmail invoice needs an address on the guest profile.
FixAdd the email in Guests, then send; or use Print.
404Invoice not found
WhyDeleted or another hotel.
Tickets, lines, discounts, splits, kitchen display, room charge, shifts and menu setup.
409Ticket is closed
WhyClosed tickets are read-only: no lines, quantities, covers, table moves, discounts, sends or splits.
400Menu item unavailable
WhyThe item is marked unavailable (86'd) or was deleted.
FixPick another item, or a Restaurant manager can mark it available in Menu.
409Line is voided
WhyA voided line cannot change quantity.
409Use void-line for sent items
WhyOnce sent to the kitchen a line cannot be deleted, it must be voided with a reason.
FixUse Void on the line and choose a reason.
400No unsent lines
WhySend to kitchen with nothing new on the ticket.
400Unknown discount
WhyThe discount was removed in Settings → Ops.
FixPick one of the listed discounts.
403Supervisor credentials required for this discount
WhyDiscounts flagged as needing authorisation (staff meal, manager comp…) need a supervisor's email and password.
FixAsk a supervisor to enter their credentials in the dialog.
403Supervisor credentials invalid
WhyWrong email or password, or the account is inactive.
403Supervisor must have Payments or Settings at Full level
WhyThe person authorising is not senior enough.
FixAsk someone with Payments Full or Settings Full.
400No active lines to split
WhySplit bill on an empty or fully voided ticket.
400lineIds required for by_item split
WhySplit by item without choosing lines.
FixTick the lines to move.
400No matching lines
WhyThe chosen lines are voided or not on this ticket.
FixRefresh and choose again.
409Cannot move KDS from new to served
WhyKitchen tickets go New → Preparing → Ready → Served, one step at a time.
409Ticket already closed
FixNothing to do; print the receipt.
400Add items before closing
FixAdd items or discard the ticket.
400Select the mobile money network
WhyMobile-money tender without MTN/Airtel.
400Room or booking required for room charge
WhyCharge to Room needs a room or booking on the ticket.
FixPick the room in the ticket head.
409No checked-in guest in that room
WhyRoom charge to a room with nobody in-house.
FixCheck the room number, or take another tender.
400Booking required for room charge
WhyThe room could not be resolved to a booking.
FixChoose the booking directly.
409No open folio for this booking. Check the guest in first
WhyRoom charges post to the stay folio, which opens at check-in.
FixCheck the guest in, or take cash/card.
409Folio is closed
WhyThe guest has checked out.
409Ticket must be closed before folio posting
WhyInternal ordering error, the ticket was not closed.
FixClose the ticket with Charge to Room again.
409Shift SHF-41 is already open for this outlet
WhyOne open cash shift per outlet (also “Shift already open for this outlet”).
FixUse the open shift, or close it first.
409Shift already closed
WhyCash-up pressed twice.
400outletId required
WhyThe shift panel was opened without an outlet.
FixPick the outlet in the bar at the top of the terminal.
400Category does not belong to outlet
WhyA menu item was added to a category from another outlet.
FixChoose a category of the same outlet.
404Outlet not found
WhyThe outlet was removed.
404Table not found
WhyThe table belongs to another outlet or was deleted.
FixChoose a table of this outlet.
Stock adjustments, purchase orders and the supplier directory.
409A supplier with that name already exists
WhySupplier names are unique per hotel, including inactive ones.
FixSearch the directory with Show inactive on; edit or reactivate the existing supplier instead.
400Name needs at least 2 characters
WhyThe supplier form was saved with an empty or one-letter name.
FixType the supplier's trading name.
400Enter a valid email
WhyThe email field has something that is not an address.
FixFix the address or leave the field blank.
400Unit cost must be a whole UGX figure
WhyA connection was saved with decimals or text in the cost.
FixEnter whole shillings, or leave the cost blank.
400The same stock item is listed twice
WhyManage items sent one item in two rows.
FixRefresh the drawer and save again.
400Unknown stock item
WhyA connection points at an item that was deleted meanwhile.
FixRefresh and pick the item again.
404Supplier not found
WhyDeleted or another hotel.
FixRefresh the directory.
400Adjustment would make quantity negative
WhyA negative adjustment larger than what is on hand.
FixCount the shelf and adjust to the real figure.
400One or more stock items not found
WhyA PO line references a deleted item.
FixRemove the line and pick a current item.
400Cannot receive PO in status received
WhyReceived and cancelled orders are final.
FixRaise a new PO for further deliveries.
400Nothing left to receive on this PO
WhyEvery line is already fully received.
FixNothing to do; the PO is complete.
404Purchase order not found
WhyDeleted or another hotel.
404Stock item not found
WhyDeleted or another hotel (also when linking a recipe).
FixRefresh and pick again.
Night audit and the export queue.
4092026-09-04 is already closed
WhyNight audit closes each hotel-local business day once.
FixNothing to do; the snapshot is in the recent audits list.
400Export is pending
WhyThe download link was opened before the file finished (status pending, running or failed).
FixWait for the live “done” update, then download. A failed export can be requested again.
404Export not found
WhyExports are kept for 30 days and then pruned.
400sort must be one of name, code, createdAt
WhyA list address carries a sort, filter or date the endpoint does not know (the wording names the field and allowed values, e.g. “from must be YYYY-MM-DD”).
FixClear the filters; use the filter bar rather than editing the URL.
Hotel settings, numbering, ops configuration.
403Changing currency, timezone or the front-desk PIN requires full Settings access
WhyThose three fields are admin-tier.
FixAsk a Super Admin or Hotel Manager.
400Unknown timezone. Use an IANA name like Africa/Kampala
WhyThe timezone must be a valid IANA zone name.
FixPick from the list, e.g. Africa/Nairobi.
404Unknown sequence
WhyThe numbering row does not exist for this hotel.
FixReload the Numbering tab.
400Next value must be above the current 2041. Lowering it would duplicate codes
WhyCounters (BK-, INV-, PAY-…) only move upward.
FixEnter a higher number.
409That void reason already exists
WhyOps items are unique by name: void reasons, checklist items, departments (“A department with that name already exists”), suppliers, inventory categories.
FixEdit the existing entry instead.
Messages specific to the public demo.
401This demo has expired
WhyYour 24-hour sandbox was swept.
FixPick a role on the sign-in page to get a new one.
403Only a demo sandbox can be reset
WhyReset was called on a real hotel.
FixNothing to do, real hotels are never reset this way.
429You have started several demos recently. Try again in an hour
WhySix sandbox starts per hour per address.
FixWait, or keep using the sandbox you have.
429Too many resets. Try again in an hour
WhyTen resets per hour per address.
503The demo is at capacity right now. Please try again in a little while
WhyThe host's live-sandbox cap (200) is reached.
FixTry again later; sandboxes expire continuously.
503Demo mode is off
WhyThis host is a real hotel, not the demo.
FixSign in with your account.
Short answers to the questions the desk asks most.
- 1
The board says Arriving Today but the list says Confirmed, which is right?
Both. Board columns are derived from status plus dates: a confirmed booking whose check-in is today (hotel time) sits in Arriving Today. Nothing is stored twice.
- 2
Why is a room Cleaning when nobody is cleaning it?
Room status is derived: out of service wins, then an in-house guest, then a blocking work order, then any open housekeeping task, then a reservation for today, else Available. An open task anywhere on the board shows as Cleaning.
- 3
Why does this invoice say Overdue when it was Pending yesterday?
Overdue is never stored, it is pending or partial with a due date before today. Record the payment and it becomes Paid.
- 4
Someone is shown Off duty but they are here.
Duty is derived: approved leave, then today's attendance mark, then a live rota window. Mark them Present in Attendance and it flips at once.
- 5
My change is not showing on another PC.
Live updates need the socket. If that PC's top bar shows Offline, its connection or the API is down; otherwise refresh once.
- 6
I checked someone in offline and now the tray says Room is already booked.
Another desk sold that room while you were offline. Open the booking, pick another ready room, check in again, then Dismiss the tray row.