Error Handling
Error envelope
Section titled “Error envelope”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 " | ". |
HTTP status codes
Section titled “HTTP status codes”| 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. |
Known error codes
Section titled “Known error codes”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.
Validation errors
Section titled “Validation errors”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.
Idempotent creates are not errors
Section titled “Idempotent creates are not errors”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.
Feature-gate errors (403)
Section titled “Feature-gate errors (403)”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.
What’s still not confirmed
Section titled “What’s still not confirmed”- Whether the exact
messagewording above will stay the same across backend versions. In production code, match oncodeand the HTTP status, not onmessagetext. - Whether
codevalues beyond the table above exist for situations not yet exercised (for example, a very malformed request body).
