Errors and rate limits

Error envelope

Business endpoint handlers return the following envelope. Validation example:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "request_id": "d68fef44-5121-4a97-9d61-a3b4631d465f",
    "details": {
      "issues": [{ "path": "party_size", "message": "Invalid value" }]
    }
  }
}

details varies by error and may be absent. Keep request_id, endpoint, HTTP status and time for support, without tokens or unnecessary customer data. Errors before the handler, including 429, may have another format and no request_id. Inspect HTTP status before parsing the JSON envelope.

HTTP	Common code	Meaning / action
`400`	`VALIDATION_ERROR`	Invalid JSON, type or field; inspect details.
`401`	`AUTHENTICATION_REQUIRED / INVALID_AUTHENTICATION`	Check full token, expiry, revocation and API feature.
`403`	`INSUFFICIENT_SCOPE / RESTAURANT_SUSPENDED`	Missing scope, or creation blocked for a suspended restaurant.
`404`	`RESOURCE_NOT_FOUND`	Resource absent or outside the restaurant context.
`409`	`RESOURCE_CONFLICT`	Duplicate external_id or POS service lock.
`422`	`VALIDATION_ERROR`	Slot unavailable or another business rule rejects the request.
`429`	`—`	Rate limit; back off before retrying.
`500`	`INTERNAL_ERROR`	Unexpected error; keep request_id for support.
`502`	`INTERNAL_ERROR`	Missed-call dispatch failure; inspect the response before retrying.

A negative exact-slot check returns 200 with data.available: false. An unbookable slot at creation returns 422, not 409. A missed-call report processed with 201 and a SKIPPED_* outcome is not an error.

Rate limits and retries

The partner route rule is configured for 600 requests per minute per client IP, not a per-key quota. When present, headers are x-ratelimit-limit, x-ratelimit-remaining and x-ratelimit-reset; reset is a Unix timestamp in milliseconds. These headers are not guaranteed on every response. On 429, reduce the request rate and back off before retrying. Do not blindly repeat a write after a timeout or server error: it may already have been stored. For reservations, search by external_id as described in the booking flow. For missed calls, reuse external_call_id and inspect the endpoint’s outcome semantics. Webhook timeouts and retries have a separate contract. For a failed missed call, an already stored row can make a retry with the same external_call_id return SKIPPED_DUPLICATE without retrying WhatsApp dispatch. Contact support to check that failure; do not change the identifier to force a new send. SENT means the WhatsApp task was scheduled, not that the customer received the message.

Overview

Meta

Authentication

Catalog

Availability

Reservations

Missed Calls

Webhooks

Errors and rate limits

Error envelope

Rate limits and retries

​Error envelope

​Rate limits and retries

Error envelope

Rate limits and retries