Let's Pizza Developersv1.0.0

Get started

Errors

Every refusal comes in one envelope, PartnerError, with a stable code and a message in two languages.

The envelope#

403 · PartnerError
{
  "code": "SCOPE_REQUIRED",
  "message": {
    "ar": "هذا المفتاح لا يملك الصلاحية المطلوبة لهذا الطلب.",
    "en": "This key lacks the scope this request needs."
  },
  "field": null,
  "retryable": false,
  "requestId": "req_01JD7Q8W3K2M",
  "detail": {
    "required": [
      "branches:read"
    ]
  }
}
  • code never changes: build your logic on it.
  • message is for people, in two languages; its wording may change.
  • field the offending field, if any.
  • retryable is true only for 408, 429 and 5xx: the same call may succeed later. False: change it first.
  • requestId is the id to quote to support.

Error codes#

CodeHTTPMeaningRetry
UNAUTHENTICATED401The API key is missing, wrong or revoked.No
KEY_EXPIRED401The API key has expired: ask for a new one.No
KEY_ENVIRONMENT_MISMATCH401This key belongs to the other environment: test keys work on the sandbox only, live keys on production only.No
PARTNER_SUSPENDED403The partner account is suspended. Contact Let's Pizza.No
IP_NOT_ALLOWED403Requests from this address are not allowed for this key.No
SCOPE_REQUIRED403This key lacks the scope this request needs.No
BRANCH_NOT_ALLOWED403This key may not act on this branch.No
RATE_LIMITED429Too many requests. Retry after the given time.Yes
INVALID_REQUEST400The request does not match the specification.No
INVALID_JSON400The request body is not valid JSON.No
PAYLOAD_TOO_LARGE413The request body is larger than allowed.No
IDEMPOTENCY_KEY_REQUIRED400This request needs an Idempotency-Key header (up to 128 characters).No
IDEMPOTENCY_KEY_REUSED422The same Idempotency-Key was used with a different request.No
NOT_FOUND404Not found.No
ORDER_NOT_FOUND404The order is not one of your orders.No
ACK_CONFLICT409The order was already acknowledged with a different number.No
STATUS_CHANGED409The order moved since you read it. Read it again, then resend.No
STATUS_NOT_ALLOWED403Your settings do not allow you to report this status.No
TRANSITION_NOT_ALLOWED—The order cannot move to this status from where it is.—
BRANCH_NOT_LIVE409Your integration is not switched on at this order's branch yet.No
EVENT_ID_REUSED409This eventId was already used for another order.No
REASON_REQUIRED422This status needs a reason: reasonCode or reasonText.No
CATALOG_SOURCE_REQUIRED403This partner is not the menu source in its settings.No
AVAILABILITY_NOT_ENABLED403Availability is not switched on for this partner.No
IMPORT_NOT_FOUND404The menu import was not found.No
SANDBOX_ONLY403This tool works on the sandbox only.No
SANDBOX_QUOTE_INVALID422The test order could not be priced: see detail.errors (the branch may be closed).No
MAPPINGS_REFUSED422The mapping request was refused whole and nothing changed: see detail.errors.No
WEBHOOK_NOT_FOUND404The subscription is not one of yours.No
WEBHOOK_INVALID422The subscription is not valid: see detail.issues.No
FIELD_REQUIRED422A field this event type needs is missing.No
CONFLICT409Conflicts with the current state.No
FORBIDDEN403Not allowed.No
INTERNAL_ERROR500Unexpected error on our side. Retry later; if it persists, send the X-Request-Id to support.Yes
SERVICE_UNAVAILABLE503The service is temporarily unavailable. Retry later.Yes

When to retry#

AnswerWhat to do
400 · 404 · 409 · 422Do not retry. Fix the call or the data first.
401 · 403Do not retry. Check the key and its scopes; alert your team.
429Wait Retry-After, then retry.
408 · 5xx · timeoutRetry with backoff (1 s, 2 s, 4 s…) and the same Idempotency-Key.