Errors

Restoo uses conventional HTTP response status codes 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 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 specification for Problem Details for HTTP APIs.

Errors are returned as JSON objects using the following media type:

Content-Type: application/problem+json

Example validation error

{
  "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."
    }
  ]
}

Reference

type · string · required

A URI identifier that categorizes the error type. When set to about:blank, it indicates a generic, non-specific error type.

title · string · required

A short, human-readable summary of the problem type.

status · integer · required

The HTTP status code generated by the origin server for this occurrence of the problem.

code · string · required

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.

detail · string · required

A human-readable explanation providing additional details about this specific occurrence of the problem.

errors · Error[]

For validation errors, provides a detailed description of each parameter that failed validation.

Error · Object

Show properties

parameter · string

The name of the input field or parameter that failed validation.

reason · string

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.