Custom store API / Errors & idempotency

Error codes and idempotency keys

For any non-2xx response, include an error code in the body. Lillo decides what to do next based on the code.

Error format

Error response

{
  "error": {
    "code": "not_allowed_in_state",
    "message": "Shipped orders can't be canceled",
    "order_status": "N30"
  }
}

HTTP	code	When	What Lillo does
400	`invalid_request`	A required value is missing or malformed (postal code, etc.)	Fails → team member reviews
401	`unauthorized`	Key missing or wrong	Fails; the console shows a connection error
403	`forbidden`	This key has no write permission	Fails → “No permission in store”
404	`not_found`	No such order, coupon or member, or the owner doesn't match	Treated as “not found”
409	`not_allowed_in_state`	Status rules don't allow it	Fails → sent to a team member with the status
409	`already_requested`	A cancellation, return or exchange is already in progress for the same item	The customer is told it's already been requested
409	`idempotency_conflict`	Same key, different body	Fails (signals a problem on Lillo's side)
409	`out_of_stock`	The exchange option is sold out	Suggests another option
409	`coupon_unavailable`	Expired, issue limit reached, or already issued	Fails → team member reviews
429	`rate_limited`	Rate limit	Fails (no automatic retry)
5xx	`internal`	Outage	Retries once with the same key, then fails

If a lookup returns 429 or 5xx, Lillo logs an error and tells the customer the team will check and follow up.

Every write carries an Idempotency-Key header (up to 64 characters).
Remember each key for at least 24 hours.
Same key + same body: don't run it again — return the original response (status code and body) as is.
Same key + different body: return 409 idempotency_conflict.
Lillo retries once with the same key only on network errors, 502, 503 or 504.

Cursors are the default. Send meta.next_cursor from the response as cursor on the next request; the last page has null.
If your store only supports Cafe24-style offsets, add "pagination": "offset" to capabilities. Lillo then sends offset and limit, and stops when it gets fewer than limit results. offset goes up to 8000.
The full catalog list always uses since_product_no, whichever pagination you choose.