Get started
Errors
Every refusal comes in one envelope, PartnerError, with a stable code and a message in two languages.
The envelope#
{
"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"
]
}
}codenever changes: build your logic on it.messageis for people, in two languages; its wording may change.fieldthe offending field, if any.retryableis true only for 408, 429 and 5xx: the same call may succeed later. False: change it first.requestIdis the id to quote to support.
Error codes#
| Code | HTTP | Meaning | Retry |
|---|---|---|---|
UNAUTHENTICATED | 401 | The API key is missing, wrong or revoked. | No |
KEY_EXPIRED | 401 | The API key has expired: ask for a new one. | No |
KEY_ENVIRONMENT_MISMATCH | 401 | This key belongs to the other environment: test keys work on the sandbox only, live keys on production only. | No |
PARTNER_SUSPENDED | 403 | The partner account is suspended. Contact Let's Pizza. | No |
IP_NOT_ALLOWED | 403 | Requests from this address are not allowed for this key. | No |
SCOPE_REQUIRED | 403 | This key lacks the scope this request needs. | No |
BRANCH_NOT_ALLOWED | 403 | This key may not act on this branch. | No |
RATE_LIMITED | 429 | Too many requests. Retry after the given time. | Yes |
INVALID_REQUEST | 400 | The request does not match the specification. | No |
INVALID_JSON | 400 | The request body is not valid JSON. | No |
PAYLOAD_TOO_LARGE | 413 | The request body is larger than allowed. | No |
IDEMPOTENCY_KEY_REQUIRED | 400 | This request needs an Idempotency-Key header (up to 128 characters). | No |
IDEMPOTENCY_KEY_REUSED | 422 | The same Idempotency-Key was used with a different request. | No |
NOT_FOUND | 404 | Not found. | No |
ORDER_NOT_FOUND | 404 | The order is not one of your orders. | No |
ACK_CONFLICT | 409 | The order was already acknowledged with a different number. | No |
STATUS_CHANGED | 409 | The order moved since you read it. Read it again, then resend. | No |
STATUS_NOT_ALLOWED | 403 | Your 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_LIVE | 409 | Your integration is not switched on at this order's branch yet. | No |
EVENT_ID_REUSED | 409 | This eventId was already used for another order. | No |
REASON_REQUIRED | 422 | This status needs a reason: reasonCode or reasonText. | No |
CATALOG_SOURCE_REQUIRED | 403 | This partner is not the menu source in its settings. | No |
AVAILABILITY_NOT_ENABLED | 403 | Availability is not switched on for this partner. | No |
IMPORT_NOT_FOUND | 404 | The menu import was not found. | No |
SANDBOX_ONLY | 403 | This tool works on the sandbox only. | No |
SANDBOX_QUOTE_INVALID | 422 | The test order could not be priced: see detail.errors (the branch may be closed). | No |
MAPPINGS_REFUSED | 422 | The mapping request was refused whole and nothing changed: see detail.errors. | No |
WEBHOOK_NOT_FOUND | 404 | The subscription is not one of yours. | No |
WEBHOOK_INVALID | 422 | The subscription is not valid: see detail.issues. | No |
FIELD_REQUIRED | 422 | A field this event type needs is missing. | No |
CONFLICT | 409 | Conflicts with the current state. | No |
FORBIDDEN | 403 | Not allowed. | No |
INTERNAL_ERROR | 500 | Unexpected error on our side. Retry later; if it persists, send the X-Request-Id to support. | Yes |
SERVICE_UNAVAILABLE | 503 | The service is temporarily unavailable. Retry later. | Yes |
When to retry#
| Answer | What to do |
|---|---|
400 · 404 · 409 · 422 | Do not retry. Fix the call or the data first. |
401 · 403 | Do not retry. Check the key and its scopes; alert your team. |
429 | Wait Retry-After, then retry. |
408 · 5xx · timeout | Retry with backoff (1 s, 2 s, 4 s…) and the same Idempotency-Key. |