> ## Documentation Index
> Fetch the complete documentation index at: https://restoo.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# Errors
> Restoo uses conventional [HTTP response status codes](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status) to indicate the success or failure of an API request and standardized error objects in JSON for responses.
## HTTP Status Code Summary
In general:
* Codes in the `2xx` range indicate success.
* Codes in the `4xx` range indicate an error that failed given the information provided (e.g., a required parameter was omitted, booking creation failed, etc.).
* Codes in the `5xx` range indicate an error with Restoo’s servers (these are rare).
| **HTTP CODE** | **DESCRIPTION** | **EXAMPLE** |
| :---------------------------- | :------------------------------------------------------------------------------------------ | :--------------------------------------------------------------------------------------- |
| **200** OK | The request was successful and the response contains the expected data. | Successfully retrieved availability (even if no slots are free). |
| **201** Created | The request was successful and a new resource was created. | A new booking was successfully created. |
| **400** Bad Request | The request has malformed syntax, missing headers, or an invalid JSON body. | The request body contains invalid JSON or missing required headers. |
| **401** Unauthorized | Authentication credentials are missing or invalid. | Missing or invalid `Authorization` token. |
| **403** Forbidden | The authenticated User or Tenant is not allowed to perform this operation. | The Tenant's plan does not include access to the Availability API. |
| **404** Not Found | The requested resource does not exist or is not accessible. | No booking found for the specified ID or invalid Venue ID. |
| **409** Conflict | The request conflicts with the current dynamic state of the server (e.g., race conditions). | Two users trying to book the last table at once, or editing an outdated booking version. |
| **422** Unprocessable Content | The request is well-formed but violates validation or static business rules. | Invalid date format, booking on a closed day, or exceeding the venue's max group size. |
| **429** Too Many Requests | The client has sent too many requests in a given amount of time. | The client exceeded the rate limit. |
| **503** Service Unavailable | The service is temporarily unavailable. | The Restoo service is undergoing scheduled maintenance. |
| **5xx** Other Server Errors | An unexpected error occurred on Restoo’s side. These are rare and usually temporary. | Unhandled server error while processing the request. |
## Handling errors
API clients must expect and gracefully handle transient server errors and rate limits. We recommend baking graceful `5xx` and `429` retries into your integration from the beginning so errors are handled automatically.
You must define an automatic retry logic strategy in order to integrate with Restoo, limiting automatic retries to 24 hs and/or 10 times with exponential back off.
We may disable your integration if we detect abuse of the Restoo API.
## Rate limiting
We return a [429 Too Many Requests](http://tools.ietf.org/html/draft-nottingham-http-new-status-02#section-4) response when you've exceeded a rate limit. Consult the `Retry-After` response header to determine how long to wait (in seconds) before retrying the request.
For a sense of scale, the first rate limit you'll commonly encounter is currently 120 requests per 1 minute period per IP address.
## Error objects
Restoo API responses use standardized error objects to provide consistent and predictable error handling across all endpoints.
These objects follow the [RFC 9457](https://www.rfc-editor.org/rfc/rfc9457.html) specification for *Problem Details for HTTP APIs*.
Errors are returned as JSON objects using the following media type:
```
Content-Type: application/problem+json
```
```json Example validation error theme={null}
{
"type": "about:blank",
"title": "Validation Error",
"status": 422,
"code": "VALIDATION_ERROR",
"detail": "The request is not valid.",
"errors": [
{
"parameter": "name",
"reason": "The name field is required."
},
{
"parameter": "email",
"reason": "The email field is required."
},
{
"parameter": "email",
"reason": "The email must be a valid email address."
}
]
}
```
```json Example business logic error theme={null}
{
"type": "about:blank",
"title": "Conflict",
"status": 409,
"code": "BOOKING_IS_NOT_ON_SEATED_GROUP",
"detail": "Booking is not on seat group"
}
```
### Reference
A URI identifier that categorizes the error type. When set to `about:blank`,
it indicates a generic, non-specific error type.
A short, human-readable summary of the problem type.
The HTTP status code generated by the origin server for this occurrence of the
problem.
A short, machine-readable string that identifies the specific error condition.
This field is specific to the Restoo API and allows client applications to
handle errors programmatically.
A human-readable explanation providing additional details about this specific
occurrence of the problem.
For validation errors, provides a detailed description of each parameter that
failed validation.
The name of the input field or parameter that failed validation.
A human-readable description of the validation error.
### Notes
* All error responses return an HTTP status code matching the `status` field.
* For validation errors (`422`), the `errors` array contains detailed information for each invalid field.
* For other types of errors (e.g., business logic or authorization), the `errors` array is omitted.
### Error codes
The following is a list of domain-specific error codes you may encounter. Generic validation errors return `VALIDATION_ERROR` with an `errors` array describing each invalid field.
#### Authentication & partner errors (HTTP 422)
| Code | Description |
| :---------------------------------- | :-------------------------------------------------------------- |
| `PARTNER_REQUIRED` | The `Restoo-Partner-Id` header is missing from the request. |
| `PARTNER_NOT_FOUND` | The partner ID in the header does not match any known partner. |
| `PARTNER_INTEGRATION_NOT_ENABLED` | This partner integration is not enabled for the target venue. |
| `PARTNER_INTEGRATION_NOT_AVAILABLE` | This partner integration is not available for the target venue. |
#### Feature errors (HTTP 403)
| Code | Description |
| :--------------------------------------------- | :--------------------------------------------------------------------------------------------------- |
| `FEATURE_PUBLIC_BOOKING_UPDATES_NOT_ENABLED` | The venue does not allow bookings to be modified from outside Restoo. Cancel and book again instead. |
| `FEATURE_PUBLIC_BOOKING_UPDATES_NOT_AVAILABLE` | The venue's plan does not include external booking updates. |
#### Booking not found (HTTP 404)
| Code | Description |
| :------------------ | :----------------------------------------------------------------------------- |
| `BOOKING_NOT_FOUND` | No booking exists for the given UUID, or it is not accessible by this partner. |
#### Booking business errors (HTTP 409)
| Code | Description |
| :------------------------------------------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BOOKING_IS_OUTDATED` | A concurrent modification conflict — the booking was updated by another request. Fetch the latest state and retry. |
| `BOOKING_IS_ALREADY_CANCELED` | The booking is already in `CANCELED` status. |
| `CUSTOMER_GDPR_CONSENT_REQUIRED` | `hasGdprConsent` was sent as `false`. A customer cannot exist without it. |
| `BOOKING_CANCELLATION_NOT_ALLOWED` | Returned by `Update Booking Status` when cancelling a booking that is already in progress. `Cancel Booking` reports a non-cancellable status as `STATUS_NOT_VALID_TO_UPDATE_PUBLIC_BOOKING` instead. |
| `BOOKING_IS_NOT_ON_SEATED_GROUP` | The operation requires the booking to be in the seated group (e.g., closing a ticket). |
| `STATUS_NOT_ON_CONFIRMED_GROUP` | The requested status transition is not valid from the booking's current status. |
| `BOOKING_STATUS_NOT_VALID` | The `status` sent on an update is not a transition allowed from the booking's current status. |
| `STATUS_NOT_VALID_TO_UPDATE_PUBLIC_BOOKING` | The booking's current status does not allow it to be modified at all. |
| `BOOKING_PARTNER_DIFFERS_FROM_CURRENT_PARTNER` | The booking was created by a different partner and cannot be modified by this one. |
| `BOOKING_AT_NOT_ALLOWED_TIME_WINDOW` | The booking date/time falls outside the venue's allowed time window for this operation. |
| `NO_AVAILABLE_SLOT` | No available slot exists for the requested date, time, and party size. |
| `BOOKING_AVAILABILITY_NOT_FOUND` | The booking could not be created or updated because the requested combination is not available. Re-run the availability flow to find out why. |
| `TABLE_NOT_MAPPED_BY_TENANT` | The table identifier provided is not mapped in this venue's configuration. |
| `BOOKING_HAS_MORE_THAN_ONE_TABLE_ASSIGNED` | The operation is not supported for bookings with more than one table assigned. |
| `BOOKING_DESTINATION_ALREADY_HAS_ASSIGNED_TICKET_EXTERNAL_ID` | The destination booking already has a POS ticket linked — cannot transfer. |
#### List bookings errors (HTTP 409)
| Code | Description |
| :---------------------------------------------- | :---------------------------------------------------------------------- |
| `GET_BOOKINGS_START_DATE_IN_PAST` | `date_start` is earlier than today. |
| `GET_BOOKINGS_END_DATE_GREATER_THAN_START_DATE` | `date_end` must be equal to or later than `date_start`. |
| `GET_BOOKINGS_RANGE_BETWEEN_DATES_EXCEED_LIMIT` | The range between `date_start` and `date_end` exceeds the 31-day limit. |