۶.۱ هدف این بخش
خطا در ارتباط بین POS و پلتفرم اجتنابناپذیر است. آنچه اهمیت دارد، نحوه واکنش سیستم به خطا است.
هدف این بخش:
- تبدیل خطا به «اقدام مشخص» برای POS
- جلوگیری از Retry اشتباه و عملیات تکراری
- حفظ همترازی دادهها (Order / Product / Inventory)
- کاهش NFC و ارجاع غیرضروری به مرکز تماس
اصل کلیدی:
همه خطاها Retry نمیخواهند؛
بعضی خطاها نیاز به اصلاح داده یا توقف جریان دارند.
۶.۲ نگاشت وضعیت HTTP به اقدام
| HTTP Status | معنی | اقدام استاندارد POS |
|---|---|---|
| 200 / 204 | موفق | ثبت نتیجه و ادامه جریان |
| 400 | خطای داده/اعتبارسنجی | نمایش پیام به اپراتور، اصلاح داده، ارسال مجدد |
| 401 | توکن نامعتبر یا منقضی | Refresh Token → در صورت شکست، Login مجدد |
| 403 | عدم دسترسی | بررسی vendorCode و مجوزهای توکن |
| 405 | Method Not Allowed | اصلاح متد یا URL اندپوینت |
| 5xx | خطای موقت سرویس/شبکه | Retry با Backoff نمایی + Idempotency |
۶.۳ خطاهای دامنه (Domain Errors)
این خطاها با HTTP 200/4xx برمیگردند ولی
تصمیمگیری اصلی بر اساس error.code انجام میشود.
| کد | شرح | اقدام پیشنهادی POS |
|---|---|---|
| 3001 | نام کاربری یا رمز عبور نامعتبر | بررسی اطلاعات ورود و تلاش مجدد |
| 3002 | client_id یا client_secret نامعتبر | بررسی تنظیمات محیط (Prod/Sandbox) |
| 3003 | توکن منقضی شده | Refresh Token |
| 3004 | عدم دسترسی/احراز ناموفق | Refresh → Login مجدد در صورت تداوم |
| 1029 | VendorCode نامعتبر | تطبیق VendorCode با توکن |
| 1023 | سفارش یافت نشد | بررسی orderCode؛ Retry نکنید |
| 1068 | Pick تکراری | بهعنوان موفق ثبت شود |
| 1059 | Accept تکراری | وضعیت جلوتر است؛ ادامه دهید |
| 1060 | Reject تکراری | سفارش نهایی شده؛ فقط ثبت داخلی |
| 503 | خطای دسترسی | در صورت موقت بودن، Retry محدود |
۶.۴ قالبهای خطای نمونه
۶.۴.۱ احراز هویت (3004)
{
"status": false,
"error": {
"code": 3004,
"message": "خطایی رخ داده است. لطفاً مجدداً امتحان کنید."
}
}۶.۴.۲ خطای اعتبارسنجی (HTTP 400)
{
"errors": {
"[comment]": "این مقدار نباید خالی باشد.",
"[nonExistentProducts][0][barcode]": "فرمت بارکد نامعتبر است."
}
}۶.۴.۳ VendorCode نامعتبر (1029)
{
"status": false,
"error": {
"code": 1029,
"message": "کد فروشگاه نامعتبر است."
}
}۶.۵ سیاست Retry (چه زمانی تکرار کنیم؟)
- Retry مجاز: Timeout، Network Error، HTTP 5xx
- Retry غیرمجاز: 400، 403، 1023، 1059، 1060، 1068
-
Backoff پیشنهادی:
1s → 2s → 4s → 8s - حداکثر تلاش: ۳ تا ۵ بار
هشدار:
Retry کورکورانه روی خطاهای منطقی
باعث عملیات تکراری و افزایش تماس مرکز تماس میشود.
۶.۶ Idempotency (الزام طراحی)
تمام عملیات حساس (Ack / Pick / Accept / Reject) باید بهصورت Idempotent پیادهسازی شوند.
- کلید پیشنهادی:
orderCode + action - در صورت دریافت خطای «قبلاً انجام شده»، عملیات را موفق تلقی کنید
- از اجرای مجدد منطق تجاری جلوگیری کنید
۶.۷ پیامهای قابلفهم برای اپراتور
| کد/وضعیت | پیام پیشنهادی |
|---|---|
| 401 / 3004 | نشست شما منقضی شده است؛ لطفاً دوباره وارد شوید. |
| 400 | اطلاعات واردشده صحیح نیست؛ لطفاً اصلاح کنید. |
| 1023 | سفارش یافت نشد یا منقضی شده است. |
| 1068 / 1059 / 1060 | این عملیات قبلاً انجام شده است. |
| 5xx | اختلال موقت؛ در حال تلاش مجدد هستیم. |
۶.۸ لاگینگ و مانیتورینگ
- ثبت:
orderCode،vendorCode، endpoint، action - ثبت HTTP Status و Domain Error Code
- ثبت latency و تعداد Retry
- عدم ذخیره دادههای حساس مشتری (PII)
- آلارم روی نرخ غیرعادی 5xx یا Timeout
فرمت لاگ پیشنهادی:
(orderCode, action, http_status, error_code, latency_ms)
۶.۹ ادامه مسیر
در بخش بعدی، استراتژی همگامسازی دادهها (Weak Signal → Full Resync) و کنترل Drift توضیح داده میشود.
رفتن به بخش ۷: استراتژی سینک