カスタムストアAPI / エラー・冪等キー
エラーコード・冪等キー
2xx以外のレスポンスでは、本文にエラーコードを入れてください。Lilloはコードを見て次の動作を決めます。
エラーの形式
エラーレスポンス
{
"error": {
"code": "not_allowed_in_state",
"message": "Shipped orders can't be canceled",
"order_status": "N30"
}
}エラーコード
| HTTP | code | 発生条件 | Lilloの動作 |
|---|---|---|---|
| 400 | invalid_request | 必須値がない、形式エラー（郵便番号など） | 失敗 → 担当者が確認 |
| 401 | unauthorized | キーなし・誤り | 失敗、コンソールに接続エラー |
| 403 | forbidden | このキーに書き込み権限がない | 失敗 → 「ストアの権限なし」 |
| 404 | not_found | 注文・クーポン・会員が存在しない、または所有者の不一致 | 「見つかりません」として処理 |
| 409 | not_allowed_in_state | ステータスのルールに合わない | 失敗 → ステータスとあわせて担当者へ |
| 409 | already_requested | 同じ商品明細でキャンセル・返品・交換がすでに進行中 | お客様には「受付済み」と案内 |
| 409 | idempotency_conflict | 同じキー、異なる本文 | 失敗（Lillo側の問題のサイン） |
| 409 | out_of_stock | 交換するオプションが品切れ | 別のオプションを案内 |
| 409 | coupon_unavailable | 期間終了・発行上限・発行済み | 失敗 → 担当者が確認 |
| 429 | rate_limited | レート制限 | 失敗（自動再試行なし） |
| 5xx | internal | 障害 | 同じキーで1回再試行した後に失敗 |
照会で429・5xxが返った場合はエラーとして記録し、お客様には確認後に改めて案内します。
冪等キー
- すべての書き込みに
Idempotency-Keyヘッダー（最大64文字）が付きます。 - 同じキーを24時間以上記憶してください。
- 同じキー＋同じ本文なら、再実行せずに最初のレスポンス（ステータスコード・本文）をそのまま返してください。
- 同じキー＋異なる本文なら、409
idempotency_conflictです。 - Lilloはネットワークエラー・502・503・504の場合にのみ、同じキーで1回だけ再送します。
ページング
- デフォルトはカーソルです。レスポンスの
meta.next_cursorを次のリクエストのcursorとして送り、最後のページはnullです。 - Cafe24方式のoffsetにしか対応していないストアは、capabilitiesに
"pagination": "offset"を入れてください。Lilloがoffset・limitを送り、受け取った件数がlimitより少なければ終わりとみなします。offsetは最大8000です。 - カタログ全件一覧は、ページング方式に関係なく
since_product_noを使います。