Skip to content

Error Handling

Every error response (menu, orders, hotels, and webhook registration) is a JSON object with a machine-readable code and a human-readable message:

{
"code": "item_not_found",
"message": "One or more menu items were not found: sku-123, sku-456."
}
Field Type Description
code string Machine-readable error code. Base your error handling on this, not on the message text.
message string Human-readable description, safe to log or show in an internal tool. For multi-field validation errors it joins each field’s errors with " | ".
Status Meaning
200 OK Successful GET, or a repeat POST to an idempotent create (the order or reservation already exists; see below).
201 Created First successful POST to an idempotent create.
400 Bad Request Request body/query params failed validation, referenced an id that doesn’t resolve to a real resource (e.g. an unknown menu item), or sent invalid dates.
401 Unauthorized Missing, unknown, or inactive Restro-API-Key, or a wrong Restro-API-Secret.
403 Forbidden Credential is valid but the tenant hasn’t enabled the module you’re calling. See Feature gating.
404 Not Found The path itself references a resource that doesn’t exist (unknown external_order_id, external_reservation_id, or room_type_id).
409 Conflict The request is well-formed but conflicts with the resource’s current state (no availability, invalid status transition, or an out-of-order update).
429 Too Many Requests You’ve exceeded the rate limit. See Rate Limits.
5xx Server Error Not covered by this error envelope. Safe to retry with backoff.

These are all the code values the backend currently returns for the menu, orders, hotels, and webhook endpoints, confirmed from the source code:

code Status Where Meaning
invalid_credentials 401 Any endpoint Missing/unknown/inactive Restro-API-Key, or wrong Restro-API-Secret.
invalid_request 400 Any endpoint with a request body Generic DRF field validation failure. message lists the field(s).
item_not_found 400 POST /orders/ One or more item_id values in the order don’t match a real menu item’s sku.
invalid_variant_id / variant_not_found 400 / 404 POST /orders/ A variant_id doesn’t exist for the given item.
invalid_addon_id / addon_not_found 400 / 404 POST /orders/ One or more addon_id values don’t exist.
room_type_not_found 404 (on POST /hotels/bookings/, GET /hotels/roomtypes/{room_type_id}/availability/) Hotel endpoints The room_type_id doesn’t exist for this tenant.
room_not_available 409 POST /hotels/bookings/, PATCH /hotels/bookings/{id}/ No availability for the requested room type/dates. On PATCH, only the newly added nights are checked.
order_not_found 404 GET /orders/{external_order_id}/, POST /orders/{id}/cancel/, PATCH /orders/{id}/payment/ No order matches this credential’s external_order_id.
reservation_not_found 404 GET/PATCH/POST /hotels/bookings/{external_reservation_id}/... No reservation matches this credential’s external_reservation_id.
invalid_status_transition 409 POST /orders/{id}/cancel/, PATCH /orders/{id}/payment/, POST /hotels/bookings/{id}/cancel/, PATCH /hotels/bookings/{id}/ The resource’s current status doesn’t allow this (e.g. cancelling something already cancelled or completed, reporting payment on a cancelled order, or changing the dates of a reservation that isn’t pending or confirmed). message includes the current status.
invalid_dates 400 PATCH /hotels/bookings/{id}/ The resulting check_in isn’t before check_out.
stale_update 409 PATCH /hotels/bookings/{id}/ A newer update (by occurred_at) has already been applied to this reservation, so this one was rejected.
rate_limited 429 Any endpoint See Rate Limits.
error varies Fallback Anything not covered above (e.g. a generic DRF exception). message contains DRF’s own detail text. Don’t rely on this text staying the same.

403 (feature-gate) responses use code: "error" with the generic DRF permission-denied message. See Feature gating.

Generic field validation (code: "invalid_request") joins each invalid field’s errors, one field per field: message segment, separated by " | ":

{
"code": "invalid_request",
"message": "quantity: Ensure this value is greater than or equal to 1."
}

Errors about a referenced id not existing (an unknown menu item, variant, add-on, or room type) use their own specific codes (see the table above) instead of the generic invalid_request.

POST /v1/restro/orders/ and POST /v1/hotels/bookings/ are idempotent on external_order_id / external_reservation_id. Retrying a create with an id you’ve already used returns the existing resource with 200 OK. This isn’t an error, and no duplicate is created. Only the first call for a given external id returns 201 Created.

A 403 from /v1/restro/orders/* or /v1/hotels/* means the tenant hasn’t enabled that module for their account:

{
"code": "error",
"message": "You do not have permission to perform this action."
}

Each module is checked independently (a hotel-only tenant’s credential is only checked against the hotel feature flag, never the restaurant one, and vice versa). So a 403 never means your credential is broken or invalid. See Feature gating.

  • Whether the exact message wording above will stay the same across backend versions. In production code, match on code and the HTTP status, not on message text.
  • Whether code values beyond the table above exist for situations not yet exercised (for example, a very malformed request body).