Errors and retries

A slow response must not turn into a second order. Keep one durable ID and request body per purchase, and separate a known validation failure from an uncertain outcome.

The retry protocol

1. Before first dispatch, atomically save your connection, external_order_id and complete request in a durable outbox.
2. On 200 or 201, persist intake confirmation. Use GET for current status.
3. On a network failure or 503, retain the request as unconfirmed and retry it unchanged. Honor Retry-After; the gateway sends 5 seconds on its 503 responses.
4. Use bounded exponential backoff with jitter. Keep the request after your retry window and surface it for reconciliation; do not silently drop it.
5. Other unexpected server/proxy errors can also have uncertain outcomes. Preserve the original identity and investigate or retry according to your recovery policy.

saved = persist_once(purchase, connection, external_order_id, full_request)

send saved.request to saved.connection
if response is 200 or 201:
    mark intake confirmed
    handle signed webhook updates
    reconcile with GET after gaps; poll only without webhooks
else if response is 429:
    retry saved.request after Retry-After plus jitter
else if timeout, network failure, or 503:
    keep unconfirmed
    retry saved.request after backoff
else:
    apply the error-specific recovery below

never create another purchase ID just because a response was lost

The gateway durably reserves validated contents before dispatch. Identical retries reuse the original snapshot even after menu changes or closure. Once reserved, an ID cannot be used for a different cart, customer, payment reference or note. There is no configurable idempotency header; external_order_id is the identity.

HTTP responses and body shapes

Read error or detail for the machine-readable code. Authentication and not-found responses normally use detail; pricing conflicts use error. Action eligibility checks can return either shape, so handle both. Validation includes sanitized field paths/types without echoing submitted customer values.

{ "error": "total_mismatch" }

{ "detail": "invalid_credentials" }

{
  "error": "invalid_request",
  "fields": [{ "path": ["body", "total"], "type": "int_type" }]
}

{ "error": "retail_unavailable", "retry_same_order_id": true }

storage_unavailable is also a 503, with {"error":"storage_unavailable"} and the same retry guidance. Do not require retry_same_order_id to be present before preserving your original identity. Reverse proxies may return non-JSON errors; handle HTTP status and transport failures before parsing a JSON body.

Conflict codes

A request rejected during initial validation is not reserved. You may correct that request for the same purchase. If there was an earlier uncertain attempt, first reconcile its original body; do not assume a later conflict erased the earlier order.

Share useful diagnostics

For support, provide the environment, connection ID used in the request URL, external order ID, timestamp, endpoint, HTTP status and error code. Redact keys, authorization headers, customer names, phones, addresses and payment details. Do not log full request bodies or downstream exceptions.

• scheduled_time_unavailable: Send a valid timestamp with an explicit timezone offset.
• cancellation_not_allowed: The order is outside the customer cancellation window or no longer in an eligible state. Immediate orders must still await acceptance; accepted scheduled orders must still await preparation and be strictly before their saved preparation start. Read current status and contact the restaurant. A receipt alone does not block an otherwise eligible scheduled cancellation.
• cancellation_conflict: A different cancellation was committed. Reconcile using the order status.

Delivery updates

delivery_update_not_allowed: wrong fulfillment or lifecycle state; read current status before retrying. delivery_update_conflict: the request ID already belongs to a different body. delivery_update_limit: the order has reached 100 distinct delivery updates. These return 409.

Refund reports

refund_report_not_allowed: the original order was not paid online. refund_report_conflict: reused request ID or processor reference. refund_amount_exceeded: the reported amount exceeds the order total or the remaining refundable amount. refund_report_limit: 100 reports already exist. All return 409; do not perform another refund just to resolve a reporting error.

tips_unavailable (409): the published menu does not enable staff tips. Remove the tip only with customer approval and recalculate before submitting a new purchase.

invalid_checkout_discount: Unknown or repeated product scope, or an amount exceeding eligible product prices. Correct the coupon before submitting a new order.

Request tracing

Gateway responses for handled /v1/ requests include X-Request-ID. Save this header with the connection ID and external order ID when reporting a problem. Each HTTP attempt gets a new request ID, including retries; it is not an idempotency key. Keep the original external order ID and request body when retrying. A network failure or proxy-generated response may have no request ID.

Rate limits

The gateway enforces limits itself, across all workers sharing its local database. Per tenant, website reads (GET/HEAD/OPTIONS) refill at 600 requests/minute with a burst of 100; writes refill at 120/minute with a burst of 30. All points of sale share these budgets. Retail publishing has a separate tenant budget of 120/minute with a burst of 30. Key rotation does not reset tenant budgets.

All /v1/ requests also share an intake budget of 6,000/minute with a burst of 1,000, including invalid credentials and malformed requests. This check runs before reading request bodies. These are continuously replenished token buckets, not calendar-minute quotas. Documentation, health checks and outbound webhook deliveries are excluded. Limits persist across restarts; independent gateway databases do not share counters.

Excess requests return 429, {"error":"rate_limit_exceeded"} and Retry-After in seconds. Wait at least that long, add jitter, then retry the same request with its original order/request ID and body. A rate-limited attempt is not forwarded to Retail. Another caller may consume the next token, so a retry can also receive 429. Use webhooks for updates and avoid aggressive polling. If limiter storage is unavailable, requests fail closed with 503 and Retry-After: 5.