Error codes
When the Clavian API refuses a request, it answers with a problem document (RFC 9457), and the document’s type is the address of one of these pages. Each page says what the failure means and what a client should do about it.
Branch on code: it names the failure and never changes. There are 130 codes, grouped here by the HTTP status each is sent with.
Codes by status
400 Bad Request
The request could not be understood as written, and has to change before it is sent again.
- Validation failed
validation_failed - That ticket code is not right
guest_ticket_invalid - Incorrect code
otp_invalid - Code expired; ask for a new one
otp_expired - This phone number cannot be used
phone_number_refused - Accept the terms and the privacy policy
consent_required - Incorrect PIN
staff_pin_incorrect - Incorrect PIN
session_pin_incorrect - This link does not work
carried_over_link_invalid
401 Unauthorized
The request came with no session, token or API key the API accepts.
- Not signed in
unauthenticated - Webhook signature not accepted
webhook_signature_invalid - Incorrect email or password
invalid_credentials
402 Payment Required
Something has to be paid for first: a session’s funding, or a capability the organisation’s plan does not include.
- Nothing to fund the session
no_funding - A pass is needed to play here
pass_required - Not included in the plan
entitlement_required
403 Forbidden
The caller is known, and may not do this: its role, a rule of the venue or a ban stops it.
- Not allowed
forbidden - Player is banned
player_banned - ID check required
id_check_required - Age restricted
age_restricted - Email address not verified
email_not_verified - Accounts are not created at this venue’s PCs
sign_up_disabled - Phone sign-in is turned off
phone_sign_in_off - Not at the venue
not_on_site - The profile can no longer be finished here
profile_window_closed - Sign in again to do this
reauthentication_required - Second factor required
second_factor_required - Invitation is for someone else
invitation_contact_mismatch - This counter device is locked
device_locked - PIN locked; a manager must reset it
staff_pin_locked - Not on a shared counter device
shared_device - Setting locked
setting_locked - A manager approves this claim
carried_over_approval_required
404 Not Found
Nothing the caller may see is there. It is also the answer wherever saying that something exists would reveal it.
- Not found
not_found - No such discount code
discount_code_unknown - No such coupon
coupon_unknown
409 Conflict
The request conflicts with the current state: something changed first, or is already so.
- Conflict
conflict - Session already ended
session_already_ended - Station not available
station_unavailable - Station reserved
station_reserved - Cannot wake the station
wake_unavailable - Already in a session
already_in_session - The wallet is not enabled here
wallet_disabled - Top-up outside the wallet’s limits
wallet_limit - Top-ups are taxed at sale here
wallet_topup_tax_at_sale - The change cannot go to the wallet
change_to_wallet_unavailable - The wallet does not hold that much cash
wallet_insufficient_cash - On account is off here
credit_disabled - Over the player’s credit limit
credit_limit_exceeded - The wallet does not hold enough
wallet_insufficient_funds - Cash refunds are turned off here
wallet_refunds_off - Adjustment over the allowed limit
wallet_adjustment_over_limit - Online payments are not available here
online_payments_unavailable - Pass product is not on sale
pass_product_inactive - Pass cannot be refunded
pass_not_refundable - This pass cannot be bought on this PC
pass_not_buyable_here - Kiosk purchases need a registered player
pass_purchase_guest - The purchase is already applied
pass_purchase_closed - Paying from an account needs a registered player
food_order_guest - This venue does not serve guests
guests_off - This guest ticket has expired
guest_ticket_expired - This guest ticket has no time left
guest_ticket_used_up - This guest ticket does not work on this PC
guest_ticket_not_here - Not for a guest
guest_session - This guest ticket cannot be claimed
guest_claim_unavailable - Pass cannot be voided
pass_not_voidable - Invitations by phone are turned off
phone_invitations_off - Sign-in link used, cancelled or expired
sign_in_handoff_unavailable - Already linked
account_already_linked - The terms or privacy policy have changed
consent_version_outdated - That email address or phone number is on another account
contact_in_use - Price changed
price_changed - Cash needs a shift
cash_needs_shift - Discount limit reached
discount_limit_reached - Discount code not active
discount_code_inactive - Discount code expired
discount_code_expired - Order below the code’s minimum
discount_code_minimum - No registered player to redeem for
coupon_no_player - Coupon not active
coupon_inactive - Coupon expired
coupon_expired - Coupon used up
coupon_used_up - Coupon already redeemed by this player
coupon_already_redeemed - Coupon not valid at this venue
coupon_not_valid_here - Invitation used, revoked or expired
invitation_unavailable - Already a member
already_a_member - An organisation needs an owner
last_owner - That role name is taken
role_name_taken - This organisation has as many custom roles as it may
custom_role_limit_reached - Role still in use
role_in_use - Marked do not contact
do_not_contact - Daily limit on first messages reached
daily_outreach_cap - Lead already converted
lead_converted - That phone number is already a lead
lead_phone_taken - The lead has no phone number
lead_no_phone - The lead has no Instagram handle
lead_no_instagram - That slug is taken
slug_taken - Business details needed first
business_details_required - Venue not ready to go live
venue_not_ready - That pass is not waiting on this session
pass_not_queued - Pass not valid at this venue
pass_not_valid_here - Top-up below the minimum
wallet_topup_below_minimum - Top-up above the maximum
wallet_topup_above_maximum - The balance would pass the maximum
wallet_balance_over_maximum - The top-up is already settled
wallet_topup_closed - More than the order still owes
tender_exceeds_outstanding - Large balances are not ticked
migration_ticks_missing - Say whether GST was charged at top-up
migration_gst_unanswered - Claim this at the front desk
carried_over_counter_only - Sign in with the email the link went to
carried_over_email_mismatch - Stock tracking is off here
inventory_disabled - Every licensed boot PC is in use
boot_licence_full - This image is already being edited
boot_edit_in_progress - Some items have not been counted
stock_count_incomplete
412 Precondition Failed
The update was based on a version of the resource that is no longer current.
- Stale write
stale_write
422 Unprocessable Content
The request is well formed, and cannot be carried out as asked.
- Cannot be processed
unprocessable - Profile incomplete
profile_incomplete - Idempotency key used for a different request
idempotency_key_reused - Enter only the last 4 digits
card_number_refused - Currency differs from the organisation's
currency_mismatch - Not a base game
not_a_base_game - The export could not be read
migration_file_unreadable
429 Too Many Requests
Too many requests in the current window. Retry-After says how long to wait.
- Too many requests
rate_limited - Too many wrong ticket codes on this PC
guest_ticket_locked - Unlocking is locked; wait or ask staff
session_unlock_locked - A demo was started too recently
demo_limit_reached
500 Internal Server Error
The API failed, and nothing the request would have changed was kept.
- Something went wrong
internal_error
503 Service Unavailable
A service the API depends on cannot do its part right now.
- Busy, try again
service_unavailable - Payment provider unavailable
payment_provider_unavailable - Codes cannot be sent right now
otp_delivery_unavailable - Game metadata provider unavailable
catalogue_provider_unavailable - Art source unavailable
art_source_unavailable
The problem document
Every error response of the API has this shape, as application/problem+json. Its schema is Problem in the OpenAPI document, which also says which codes each endpoint can answer with.
type- The address of the failure’s page here, which says what it means and what to do.
title- A short summary of the failure. The same for every occurrence of a
type, and not translated. status- The HTTP status of the response, repeated.
detail- What went wrong this time, for people to read. It changes from one occurrence to the next, and never says whether an account exists. Optional.
code- The failure in snake case: the member a client branches on. It never changes for a failure.
requestId- The request’s id: also its
X-Request-Idheader and its trace id. Quote it to support. errors- For a validation failure, one entry for each field that failed: its
field, acodeand amessage. Optional. instance- A reference to this occurrence, where the API gives one. Optional.
activeSession- Only on
already_in_session: where the player’s running session is, as itsstationandvenuenames, so a client can say where and offer to move it. Optional. total- Only on
price_changed: the total the server computes now, as money in minor units, so a client can show it and ask the person to confirm before sending again. Optional. missingSteps- Only on
venue_not_ready: the venue’s essential setup steps still missing —openingHours,price,stationPaired— in order, so a client can name each one beside Go live. Optional.
Answers from /v1/auth/
The sign-in endpoints under /v1/auth/ answer in a shape of their own instead, { "code", "message" }, with the code in upper snake case. The OpenAPI document calls it AuthError; its codes have no pages here.