Booking API error codes

This reference lists the errors your application is most likely to meet when it builds a cart and completes checkout with the Booking API, and how to react to each one.

How errors are reported

The Booking API reports problems in two places.

Where	When	What to do
Top-level `errors` of the response	Validation failed before execution, or a field failed during execution.	Fix the request. For a token of the wrong kind, send the correct cart or invoice token. See the token recovery guidance below.
`errors` in the mutation result	The operation ran and was rejected, for example because a time slot is sold out.	Branch on `message`, show `messageTranslated`, and let the customer correct the input.

Schema validation and variable coercion errors prevent execution. Errors raised during execution can accompany partial data: another mutation field may already have succeeded and saved changes. Top-level errors do not prove that no write occurred. Inspect the returned data and each error's path, and read the cart and any invoice before repeating writes.

Each mutation error has three fields:

Field	Content
`key`	The input the error refers to, as a path such as `requestItems.0.pricings.0.quantity`. Indexes count from 0.
`message`	A machine-readable code such as `invalid`. Use it to decide how your application reacts.
`messageTranslated`	Text in the `Accept-Language` language for customers. For some codes, such as `missing_required`, it repeats the code; show your own text for those.

Do not branch on messageTranslated: its wording can change. The messages and messagesTranslated lists are deprecated.

Top-level errors

Message contains	Cause	What to do
`Not authorized`	The cart or invoice token is invalid or has expired.	For an unusable or expired cart token, start a new cart. For an invoice, use a valid token for that same invoice.
`expected: Request`	A token of the wrong kind was sent, for example an invoice token as the cart token.	Send the cart token.
`was provided invalid value`	A variable does not match its input type.	Check the variables against the reference.
`doesn't exist on type`	The query selects a field that the Booking API does not offer.	Remove the field or check the reference.

Adding and changing cart lines

These errors come from requestItemCreate, requestItemUpdate and requestItemDiscard, and from lines sent with requestUpdate. Keys start with requestItems.0 even when you add a single line.

Key	Message	Cause	What to do
`requestItems.0.pricings.0.quantity`	`sum_less_than_or_equal_to`	Not enough places are left for the requested quantity.	Lower the quantity or let the customer choose another date or slot.
`requestItems.0.pricings.0.quantity`	`greater_than_or_equal_to`, `less_than_or_equal_to`	The quantity is outside the price category's minimum or maximum number of people.	Adjust the quantity.
`requestItems.0.offerableSpan`	`required`, `invalid`	An event template or admission line has no time slot, or the slot does not exist.	Send a `span` returned by the time slot query.
`requestItems.0.offerableId`	`invalid`	The offer does not exist or is not published.	Reload the offers.
`requestItems.0.offerableId`	`exclusively_booked`	Another customer has booked the whole event exclusively.	Let the customer choose another event.
`resourceRequirements`	`no_available_resources`	Staff or rooms needed for the booking are not available at that time.	Let the customer choose another time.
`requestId`	`invalid`	The cart does not exist or its reservation expired.	Start a new cart.
`requestId`	`not_editable`	The order was canceled or can no longer be changed, for example after it was paid.	Start a new cart for further purchases.
`checkoutHold`	`expired`	The checkout hold ended and KORONA Event canceled the cart.	Start a new cart.
`id`	`locked`	Checkout is running for this cart at the same moment.	Wait briefly and read the cart before trying again.

Customer data

These errors come from requestUpdate.

Key	Message	Cause	What to do
`contact.email`	`blank`	The email address is missing.	Ask for an email address.
`contact.email`	`invalid_address`	The email address is not valid.	Ask the customer to correct it.
`id`	`payment_exists`	A payment for this cart is in progress.	Do not change the cart. Follow the payment on the invoice.
`id`	`already_canceled`	The cart was canceled.	Start a new cart.

Codes

These errors come from requestApplyCode and requestRemoveCode.

Key	Message	Cause	What to do
`code`	`invalid`	The code is unknown, expired, used up, has no remaining value, is already applied, or does not apply to the cart. When removing, the code is not applied to the cart.	Tell the customer the code cannot be used.
`code`	`already_redeemed`	A promotion code has reached its redemption limit.	Tell the customer the code cannot be used.
`requestItem`	`blank`	The voucher must be redeemed for a product. The result lists the choices in `followUpProducts`.	Let the customer choose a product and apply the code again with `requestItem`.
`requestId`	`not_editable`	The order can no longer be changed.	Start a new cart.

Checkout

These errors come from requestPaymentInitiate. For input validation errors, correct the input before trying again. An expired checkout hold cancels the cart. With id:locked, another checkout may still finish and change the cart; wait and read the cart and any invoice before deciding whether checkout is still needed.

Key	Message	Cause	What to do
`contact`	`blank`	The cart has no customer.	Add the customer with `requestUpdate` first.
`legalDocumentAcceptances`	`missing_required`	A required legal document was not accepted.	Show the document and send its acceptance.
`legalDocumentAcceptances.0.legalDocumentVersion`	`invalid`	The accepted version is not the current one. The document changed after it was shown.	Reload the documents, show them again and send the new `publishedAt`.
`legalDocumentAcceptances.0.legalDocumentId`	`invalid`	The document does not exist.	Reload the documents.
`withdrawalEarlyStartConsent`	`missing_required`	A cart line needs the customer's consent to start before the withdrawal period ends.	Ask for the consent and send it with `accepted: true`.
`withdrawalEarlyStartConsent`	`invalid`	`requestItemIds` does not list exactly the lines that need consent.	Send the ids of every line with `requiresWithdrawalEarlyStartConsent`.
`id`	`custom_fields_incomplete`	Required booking or attendee details are missing.	Send the customer to the hosted pages that collect them, or collect them before checkout.
`checkoutPolicy`	`TARGET_STATE_CONFLICT`, `PAYMENT_METHOD_CONFLICT`	The cart mixes offers that cannot be checked out together.	Split the cart.
`checkoutHold`	`expired`	The checkout hold ended and the cart was canceled.	Start a new cart.
`id`	`locked`	Another checkout request for this cart is running.	Wait and read the cart and any invoice before deciding whether checkout is still needed.

Expired checkout holds

Send exactly one of requestId (the cart token) or invoiceToken to requestCancelExpiredCheckoutHold. If an anonymous caller omits both, the response has a top-level Not authenticated error. Send one of the tokens and retry.

The mutation can return these payload errors:

Key	Message	Cause	What to do
`checkoutHold`	`not_expired`	The hold is still running.	Wait until `secondsRemaining` reaches zero.
`id`	`invalid`	Both `requestId` and `invoiceToken` were sent.	Send exactly one of them.
`id`	`blank`	An authenticated caller omitted both `requestId` and `invoiceToken`.	Send exactly one of them.

General codes

Other inputs use these general codes.

Message	Meaning
`blank`, `required`	A required value is missing.
`invalid`	The value is not allowed or does not exist.
`taken`	The value must be unique and is already used.
`greater_than_or_equal_to`, `less_than_or_equal_to`	The value is below the minimum or above the maximum.