Errors and limits

Errors

The shape of an error, every error code the API answers with, and what to do about each one.

When a request fails, the answer carries an HTTP status that says what happened, an error code to act on and two messages. This guide covers the shape of an error, every error code the API answers with, and which errors to retry.

An error#

JSON

{
  "success": false,
  "timestamp": "2026-10-01T09:30:00.123Z",
  "traceId": null,
  "userMessage": "Table not found at this venue.",
  "developerMessage": "The table is not one of this venue's tables.",
  "errorCode": "PUBLIC_API_TABLE_NOT_FOUND",
  "validationErrors": [
    { "field": "tableId", "message": "Not one of this venue's tables.", "attemptedValue": null }
  ],
  "details": null
}

successboolean

Whether the call succeeded. Always false in an error.

timestampstring · date-time

When the answer was written, in UTC.

traceIdstringnullable

Identifies the request in Cibusy's logs, when it is set. Quote it when you write to support.

userMessagestringnullable

A sentence for the person using your site, in the language of the Accept-Language header.

developerMessagestringnullable

For you and your logs, in English. Its wording may change; do not parse it.

errorCodestringnullable

The stable code to act on, such as PUBLIC_API_VENUE_NOT_FOUND. Every one is listed in Errors.

validationErrorsobject[]nullable

When the error is about parts of the request, each one by its path in the body (lines[1].extraIds). null otherwise.

Fields of Field error

fieldstring

The path of the part in the request body: customer.phone, lines[0].quantity.

messagestring

What is wrong with it, in short, in English.

attemptedValueanynullable

The value that was sent. The public API sends it as null.

detailsanynullable

Room for further detail. The public API sends it as null.

The answer to a call over the rate limit is slightly different: it has no validationErrors or details, and says how long to wait in retryAfter. Rate limits covers it.

Handling an error#

Decide from the status and errorCode. The wording of messages may change; codes do not.
userMessage is for your guest. It is a sentence for the person using your site and can be shown as it is. Its language is chosen with the Accept-Language header.
developerMessage is for you. It is in English and meant for your logs. Its wording may change; do not decide anything from its content.
validationErrors says what was wrong. When an error is about one part of the request, that part is named by its path in the request body: lines[1].extraIds, say. Your form can show the error beside the field it is about.
Keep traceId when it is set. It finds the request in Cibusy's logs; include it when you write to support.

Error codes#

HTTP	Code	Meaning
400	`VALIDATION_ERROR`	A parameter or the JSON body could not be read: a value that is not a UUID or not one of an enum's names, or malformed JSON. `validationErrors` names the fields.
400	`INVALID_PAGE_NUMBER`	`cursor` is below 1.
400	`INVALID_PAGE_SIZE`	`pageSize` is outside 1 to 100.
400	`PUBLIC_API_IDEMPOTENCY_KEY_INVALID`	The `Idempotency-Key` header is missing, or is not 8 to 64 letters, digits, `-` or `_`.
400	`PUBLIC_API_ORDER_INVALID`	The request breaks the shape rules for its order type, table, customer or lines. Every problem found is in `validationErrors`.
400	`PUBLIC_API_PRODUCT_OPTION_INVALID`	An extra or removed ingredient is not the product's own, is repeated, or breaks the product's option groups.
400	`PUBLIC_API_RESERVATION_INVALID`	The reservation request breaks the shape rules: the time, the number of guests, the guest's name or phone is missing or wrong, or a text is too long. Every problem found is in `validationErrors`, by its path in the request.
400	`TOO_MANY_GUESTS`	The booking is for more than 20 guests. A larger party books by calling the venue.
400	`INVALID_RESERVATION_DATE`	The time asked for has already passed.
401	`PUBLIC_API_KEY_MISSING`	There is no `X-Api-Key` header.
401	`PUBLIC_API_KEY_INVALID`	The key is malformed, unknown or revoked, or its venue has closed. One answer for all of them, so it never says which. Check whether the key is still listed in the panel.
403	`PUBLIC_API_SCOPE_MISSING`	The key is good but was not made with the permission this call needs: "Can send orders" for the order calls, "Can take reservations" for the reservation calls. The permission can be given on the API keys page of the panel, and applies from the key's next request.
404	`PUBLIC_API_VENUE_NOT_FOUND`	The venue does not exist, or this key cannot reach it. Both get the same answer, so a key never learns which venues exist beyond its own.
404	`PUBLIC_API_ORDER_NOT_FOUND`	No order with this id was placed through the API at a venue this key reaches.
404	`PUBLIC_API_RESERVATION_NOT_FOUND`	No reservation with this id was taken through the API at a venue this key reaches. A booking the venue took some other way answers the same.
404	`PUBLIC_API_TABLE_NOT_FOUND`	A dine-in order names a table that is not one of the venue's. Read the tables with `GET /venues/{venueId}/tables`.
404	`PUBLIC_API_PRODUCT_NOT_FOUND`	A product or portion in the order is not on the venue's menu. Refresh your copy of the menu.
409	`PUBLIC_API_PRODUCT_UNAVAILABLE`	A product cannot be ordered: it is hidden from the menu, sold by weight, or out of stock.
409	`PUBLIC_API_ORDERING_UNAVAILABLE`	The venue has no active subscription, so it takes no orders. The menu can still be read.
409	`PLACE_IS_BUSY`	The venue's kitchen has declared a rush. `ordering.busyUntil` on the venue says until when.
409	`OUTSIDE_WORKING_HOURS`	The venue is closed right now.
409	`ORDER_CREATION_IN_PROGRESS`	A request with the same `Idempotency-Key` is still being processed. Send yours again with the same key and you receive the order.
409	`PUBLIC_API_RESERVATIONS_UNAVAILABLE`	The venue has no active subscription, so it takes no reservations.
409	`RESERVATIONS_DISABLED`	The venue has switched bookings off. `reservationsEnabled` in the availability answer says so beforehand.
409	`RESERVATION_TOO_SOON`	The time asked for is less than 30 minutes away. Pick a later one.
409	`RESERVATION_TOO_FAR`	The time asked for is more than 60 days ahead. `lastBookableDate` in the availability answer says the last day.
409	`RESERVATION_TIME_UNAVAILABLE`	The venue does not seat at that time: it is shut, or the time is outside its booking hours. Take the time from the availability answer.
409	`RESERVATION_NOT_CANCELLABLE`	The reservation can no longer be called off: the guest has been checked in, its time has come, or it is already over (declined, completed). `canCancel` on the reservation says so beforehand.
409	`PUBLIC_API_WEBHOOK_NOT_CONFIGURED`	The key has no webhook address, when a test event or a new signing secret is asked for. Add one on the panel's API keys page.
429	`RATE_LIMIT_EXCEEDED`	The key is over its budget. Wait `Retry-After` seconds.
500	`INTERNAL_ERROR`	A fault on Cibusy's side. Try again after a pause; an order is retried with the same `Idempotency-Key`.

Which errors to retry#

Answer	What to do
`429` `RATE_LIMIT_EXCEEDED`	Wait the number of seconds in the `Retry-After` header, then try again.
`500` `INTERNAL_ERROR`	Try again after a pause. Send an order again with the same `Idempotency-Key`, and a reservation again unchanged.
`409` `ORDER_CREATION_IN_PROGRESS`	Shortly after, send it again with the same `Idempotency-Key`; you receive the order.
A timeout or a dropped connection	Repeat a read. Send an order again with the same `Idempotency-Key`: if it was placed, you receive it. Send a reservation again unchanged: if it was taken, you receive it.
`409` `RESERVATIONS_DISABLED`, `PUBLIC_API_RESERVATIONS_UNAVAILABLE`	Do not retry straight away: the venue is not taking reservations now. Tell the guest with `userMessage`.
`409` `RESERVATION_TOO_SOON`, `RESERVATION_TOO_FAR`, `RESERVATION_TIME_UNAVAILABLE`	The same time gets the same answer. Read the bookable times again and let the guest pick another.
`409` `PLACE_IS_BUSY`, `OUTSIDE_WORKING_HOURS`, `PUBLIC_API_ORDERING_UNAVAILABLE`	Do not retry straight away: the venue is not taking orders now. Tell the guest with `userMessage`. `ordering.busyUntil` in the venue's details says when a rush ends.
Any other `4xx`	The same request gets the same answer. Do not retry it until you have fixed the request or the key.

Every rule for retrying an order safely is in Placing orders, and for a reservation in Taking reservations.

The panel's error codes#

The API never answers with these four codes; the venue's owner may see them in the panel while setting up keys and webhooks. They are listed so that every code a venue may pass on to you is explained:

HTTP	Code	Meaning
400	`PUBLIC_API_KEY_NAME_INVALID`	The key's name must be 1 to 60 characters.
400	`PUBLIC_API_WEBHOOK_URL_INVALID`	The webhook address must be a public `https://` URL; private, local and internal addresses are refused.
404	`PUBLIC_API_KEY_NOT_FOUND`	The key being changed in the panel does not exist, or has been revoked.
409	`PUBLIC_API_KEY_LIMIT_REACHED`	A venue can have at most 10 working keys. Revoke one it no longer uses to make another.