مدیریت خطاها – Error handling

• مقدمه ای بر Error Handling
• نحوه نگارش خطاها
• Status Code – کدهای وضعیتی درخواست ها
• خطاهایی که در قالب Response دریافت میشود
• دریافت جزئیات خطا از طریق API
• سربرگ – Header
• مقادیر ارسالی – Request Data
• پاسخ صحیح – Response True
• پاسخ نادرست – Response False

مقدمه ای بر Error Handling

قبل از هر چیز لازم است بدانیم مدیریت خطا یا error handling به چه معناست. این اصطلاح به واکنش و مکانیسم‌های بازیابی نرم‌افزار در صورت بروز خطا اشاره می‌کند. به عبارت دیگر این کار فرآیندی است که شامل پیش‌بینی دقیق، شناسایی و رفع خطاها در برنامه‌ها است.

اجرای منظم یک برنامه از طریق مدیریت خطا آسان‌تر است. وقتی صحبت از رویکردهای خطا handling می‌شود، بسیاری از برنامه‌ها با مشکلات معماری نرم‌افزار مواجه می‌شوند.

توجه داشته باشید که API AirPlus کامل منطق بر اصول RESTful API نوشته شده است پس بنابراین پاسخ تمام درخواست ها با Status Code مورد نظر خود ارسال خواهد شد و مدیریت این Status Code ها یا هما کدهای وضعیتی در برنامه شما الزامیست.

طبق اصول کلی تمام پاسخ های صحیح با کد وضعیتی 200 ارسال خواهند شد.

اما اتوماسیون ایرپلاس در زمینه مدیریت خطاها هم مستندات جامع و کاربردی را تهیه نموده است.

نحوه نگارش خطاها

پاسخ نادرست – Response False یا همان مشکل در ارسال اطلاعات

{
    "status": false,
    "time": "Timestamp", // Timestamp
    "code": "Error Code"
}

Status Code – کدهای وضعیتی درخواست ها

 وضعیت 200 — OK

کد وضعیت 200 OK نشان می‌دهد که درخواست به‌درستی توسط سرور دریافت، درک و پردازش شده و پاسخ استاندارد حاوی داده‌های درخواست‌شده را بازگردانده است.

طبق RFC 9110 (HTTP Semantics, 2022)، این کد برای موفقیت عمومی تمام متدهای HTTP استفاده می‌شود؛ در پاسخ به GET معمولاً به معنی دریافت محتوای صحیح است، در PUT و DELETE به معنی انجام کامل عملیات است.

در صورت دریافت 200، کلاینت می‌تواند فرض کند که هیچ خطایی در فرآیند ارتباط وجود نداشته و پاسخ معتبر است.

 وضعیت 201 — Created

کد 201 Created نشان می‌دهد که درخواست با موفقیت انجام شده و منبع جدیدی ایجاد شده است.

بر اساس RFC 9110، این پاسخ اغلب برای متدهای POST و گاهی PUT استفاده می‌شود. سرور می‌تواند هدر Location را شامل URI منبع تازه ایجادشده برگرداند تا کلاینت بتواند به آن دسترسی پیدا کند.

نمونه: هنگام ثبت سفارش یا خرید بلیت، اگر ایجاد آیتم در پایگاه داده موفقیت‌آمیز باشد، سرور وضعیت 201 بازمی‌گرداند.

 وضعیت 204 — No Content

کد 204 No Content به معنی موفقیت‌آمیز بودن درخواست بدون نیاز به ارسال محتوای جدید در پاسخ است.

این کد معمولاً در پاسخ به متدهای PUT, PATCH, DELETE یا POST استفاده می‌شود، زمانی‌که عمل مورد‌نظر در سرور انجام شده ولی داده‌ای برای بازگرداندن وجود ندارد.

مثال: API حذف رزرو در صورت موفق بودن حذف، بدون بدنهٔ پاسخ، وضعیت 204 ارسال می‌کند.

 وضعیت 207 — Multi‑Status

کد 207 Multi‑Status بخشی از استاندارد WebDAV (RFC 4918) است.

این کد زمانی استفاده می‌شود که یک درخواست شامل چندین عملیات یا منبع باشد و پاسخ برای هر مورد جداگانه در قالب XML یا JSON شامل وضعیت مجزا ارائه گردد.

به‌طور مثال در یک درخواست جمعی برای بروزرسانی چند فایل، اگر بعضی پردازش شوند و بعضی خطا بدهند، پاسخ 207 حاوی نتیجهٔ جزئی هر فایل ارسال می‌شود.

 وضعیت 400 — Bad Request

کد 400 Bad Request نشان‌دهندهٔ آن است که سرور نمی‌تواند یا نمی‌خواهد درخواست را پردازش کند زیرا در نحو (syntax) یا ساختار داده‌های درخواست خطا وجود دارد.

علل رایج: بدنه غیرقابل parse شدن، مقادیر ناقص، هدرهای نادرست یا شناسهٔ توکن نامعتبر.

این خطا ناشی از اشتباه سمت کلاینت است و معمولاً با پیام‌هایی نظیر invalid JSON یا missing parameter همراه می‌شود.

 وضعیت 404 — Not Found

کد 404 Not Found زمانی برگردانده می‌شود که منبع یا مسیر مورد نظر در سرور وجود ندارد یا حذف شده است.

از دید API یعنی Endpoint یا URI درخواستی شناسایی نمی‌شود.

دلایل معمول: آدرس غلط، تغییر نسخهٔ سرویس، پایان پشتیبانی از مسیر قبلی (deprecated endpoint).

راه‌حل: بررسی مجدد URL و در صورت نیاز به‌روزرسانی URI مورد استفاده.

 وضعیت 405 — Method Not Allowed

کد 405 Method Not Allowed یعنی URI مورد درخواست معتبر است، اما متد (مثلاً POST یا DELETE) توسط سرور برای آن مسیر مجاز نیست.

در پاسخ معمولاً هدر Allow شامل لیستی از متدهای مجاز مثل GET, PUT برگردانده می‌شود.

این خطا از نوع کلاینت است و نشانهٔ استفاده از متد غیرفعال برای endpoint خاص می‌باشد.

 وضعیت 409 — Conflict

کد 409 Conflict به معنی وجود تعارض در وضعیت فعلی منبع است که مانع انجام عملیات می‌شود.

این خطا زمانی بازگردانده می‌شود که درخواست در تضاد با داده‌های موجود باشد، مثلاً تلاش برای ایجاد رکورد تکراری یا بروزرسانی نسخهٔ قدیمی شیء.

در سيستم‌های دارای نسخه‌بندی و کنترل همزمان (مثل وب‌سایت رزرو یا فرم ثبت آیتم تکراری) کاربرد دارد.

 وضعیت 422 — Unprocessable Entity

کد 422 Unprocessable Content (نام جدید در RFC 9110، ‌قبلاً Unprocessable Entity در RFC 4918 بود) زمانی ارسال می‌شود که درخواست از نظر نحوی درست است ولی داده‌های آن از نظر منطقی یا اعتبارسنجی نامعتبر است.

مثلاً فیلدهای الزامی خالی‌اند یا مقادیر بعضی پارامترها خارج از محدودهٔ مجاز هستند.

این کد معمولاً در APIهایی که قبل از پردازش داده، validation دقیقی انجام می‌دهند (مثلاً در فرم‌های ثبت اطلاعات) استفاده می‌شود.

 وضعیت 500 — Internal Server Error

کد 500 Internal Server Error بیانگر خطای عمومی در سمت سرور است، بدون اشاره به علت دقیق.

معمولاً در اثر بروز استثنا (Exception)، نقص در پیکربندی، یا قطع ارتباط سرویس وابسته رخ می‌دهد.

این خطا قابل تشخیص برای کلاینت نیست و صرفاً به معنی شکست درخواست در سطح سرور است.

توصیهٔ استاندارد: بررسی log سرور، و در صورت نیاز ارائه سرویس پشتیبان یا fallback endpoint برای حفظ پایداری ارتباط.

خطاهایی که در قالب Response دریافت میشود

این خطا ها در قالب Response False بصورت کد دریافت میشوند که میتوانید در متن خطا ها و راه حل آنها را در جدول زیر مشاهده نمائید.

در ضمن میتوانید از طریق API زیر بصورت داینامیک این خطاها را دریافت و مدیریت نمائید.

دریافت جزئیات خطا از طریق API

سربرگ – Header

در این روش شما باید درخواست خود را از طریق لینک زیر ارسال فرمائید.

{{Api Url}}/error-handling

HEADER
GET /api/reservation/{{Api version}}/error-handling HTTP/1.1
Host: {{Your Host}}
Authorization: Bearer JWTToken
Content-Type: application/json
Domain: {{Your Domain}}

API Url از طریق پنل کاربری قابل مشاهده خواهد بود

مقادیر ارسالی – Request Data

{
    "code": "Error Code"
}

پاسخ صحیح – Response True

دریافت این پاسخ با Status Code 200 دریافت خواهد شد.

{
    "status": true,
    "time": "Timestamp", // Timestamp
    "data": [
        {
            "title": "Error title in Persian",
            "solution": "How to solve errors in Persian"
        },
        ...
    ]
}

پاسخ نادرست – Response False

{
    "status": false,
    "time": "Timestamp", // Timestamp
    "code": "Error Code"
}