خطای وب سرویس (Web Service Error) به هرگونه مشکلی گفته می شود که هنگام فراخوانی، ارسال درخواست یا دریافت پاسخ از یک وب سرویس (مثل APIهای REST، SOAP یا سرویس های مبتنی بر HTTP) رخ می دهد.
| نوع خطا | کد یا نام رایج | توضیح کوتاه |
|---|---|---|
| خطای سمت کلاینت | 400, 401, 403, 404 | درخواست اشتباه، احراز هویت ناموفق، دسترسی غیرمجاز یا منبع پیدا نشد |
| خطای سمت سرور | 500, 502, 503, 504 | مشکل داخلی سرور، در دسترس نبودن سرویس یا تایم اوت |
| خطای ارتباطی | Timeout, Connection refused | قطع ارتباط شبکه، کندی یا عدم پاسخ سرور |
| خطای منطقی/کسب وکار | Fault در SOAP یا کد خطای سفارشی در JSON | داده نامعتبر، قوانین کسب وکار نقض شده |
| خطای امنیتی | SSL/TLS error, Certificate error | مشکل در گواهی امنیتی یا رمزنگاری |
دلایل رایج وقوع خطا
- درخواست نادرست (پارامترهای اشتباه، فرمت JSON/XML نامعتبر)
- مشکل در احراز هویت یا مجوز دسترسی (Token منقضی، API Key اشتباه)
- در دسترس نبودن سرویس یا overload شدن سرور
- مشکل شبکه یا فایروال
- باگ در کد سمت سرور
- ناسازگاری نسخه API
نحوه تشخیص و رفع
- کد وضعیت HTTP را بررسی کنید (مثلاً با ابزارهایی مثل Postman یا لاگ ها).
- پیام خطا و جزئیات (message، code، stack trace) را بخوانید.
- لاگ های سمت کلاینت و سرور را چک کنید.
- در صورت نیاز، درخواست را با پارامترهای صحیح دوباره ارسال کنید یا با پشتیبانی سرویس دهنده تماس بگیرید.
خطای وب سرویس دقیقاً چیست؟
وقتی برنامه شما درخواستی (Request) به سمت سرور ارسال می کند، سرور یک پاسخ (Response) برمی گرداند. اگر همه چیز درست پیش برود، این پاسخ با کدهایی در بازه ۲۰۰ باز می گردد؛ ولی اگر مشکلی در مسیر رخ دهد، سرور یک کد خطا یا Error Code به همراه پیام توضیحی ارسال می کند.
نکته: خطای وب سرویس همیشه به معنای خرابی سرویس نیست. گاهی مشکل از سمت شماست (مثلاً پارامتر نامعتبر فرستاده اید)، گاهی از سمت سرور و گاهی حتی از شبکه ای که بین این دو قرار دارد. شناخت دقیق این تفاوت، اولین قدم برای رفع خطای وب سرویس است.
جدول سریع کدهای خطای وب سرویس و راه حل آن ها
قبل از هر توضیح اضافه تری، نگاهی به جدول زیر بیندازید تا بدانید معنی و راه حلی هر خطای وب سرویس چیست. در ادامه مقاله وارد جزئیات بیشتری خواهیم شد.
| کد خطا | معنی | راه حل سریع |
|---|---|---|
| 400 | ساختار درخواست نامعتبر است (JSON بد یا پارامتر ناقص) | بررسی بدنه درخواست و Content-Type |
| خطای 401 | احراز هویت انجام نشده یا API Key نامعتبر است | تازه سازی کلید و بررسی هدر Authorization |
| 403 | هویت تایید شده ولی دسترسی مجاز نیست | بررسی سطح دسترسی، آی پی مجاز و پلن سرویس |
| 404 | آدرس یا منبع درخواستی وجود ندارد | کنترل صحت URL و مسیر endpoint |
| خطای 429 | عبور از سقف تعداد درخواست (Rate Limit) | رعایت هدر Retry-After و اجرای backoff |
| 500 | خطای داخلی و غیرمنتظره در سرور | تلاش دوباره با فاصله زمانی و ثبت لاگ |
| 503 | سرور موقتاً در دسترس نیست (بار زیاد یا نگهداری) | صبر و retry، بررسی وضعیت سرویس |
همان طور که در جدول مشاهده می کنید، تعریف رسمی این کدها ثابت است. برای مثال در کد ۴۰۰ سرور به این دلیل که چیزی را خطای سمت کاربر تشخیص داده، درخواست را رد می کند.
اما پاسخ ۴۰۱ به این معناست که کلاینت باید برای دریافت پاسخ درخواستی، ابتدا باید خودش را احراز هویت کند. برای فهم کامل تر منطق این کدها، بهتر است سری هم به مطلب Status Code چیست بزنید تا با کل خانواده کدهای وضعیت HTTP آشنا شوید.
سه دسته اصلی خطای وب سرویس
خطاهای وب سرویس معمولاً در سه گروه اصلی جای می گیرند. شناخت این دسته بندی به شما می گوید که اصلاً باید دنبال مشکل در کد خودتان بگردید یا باید صبر کنید تا سرور مشکلش را حل کند.
خطای سمت کاربر (4xx)
وقتی کدهای دسته 4xx را می بینید، یعنی مشکل از درخواستی است که شما فرستاده اید. در واقع، خطاهای سمت کلاینت زمانی رخ می دهند که خود درخواست اشتباه است و می تواند دلایل مختلفی داشته باشد، مثل:
- نحوه نادرست ارسال درخواست
- احراز هویت گم شده یا نامعتبر
- دسترسی ناکافی
- عبور از سقف نرخ درخواست
- آدرس دهی به منبعی که وجود ندارد
در این حالت کلاینت باید چیزی را تغییر دهد و دوباره تلاش کند. یعنی تا زمانی که شما چیزی در کد یا پارامترهای ارسالی اصلاح نکنید، همان درخواست همیشه همان خطا را برمی گرداند.
خطای سمت سرور (5xx)
اینجا داستان برعکس است. خطاهای دسته 5xx زمانی رخ می دهند که سرور در پردازش یک درخواست معتبر شکست می خورد.
دلایلش هم می تواند اضافه بار، استثناهای داخلی، عدم دسترسی به سرویس های بالادستی یا خرابی برنامه ریزی شده سرور باشد. در این حالت شما هیچ کاری اشتباه نکرده اید و تنها کاری که باید بکنید صبر کردن و تلاش دوباره (retry) با فاصله زمانی مناسب است.
خطای شبکه و اتصال
دسته سوم اصلاً یک کد HTTP مشخص برنمی گرداند، بلکه اتصال قبل از رسیدن به سرور قطع می شود.
دو نمونه بسیار رایج این دسته عبارتند از:
- خطای CORS: زمانی رخ می دهد که مرورگر به دلیل سیاست های امنیتی، اجازه ارسال درخواست از یک دامنه به دامنه دیگر را نمی دهد.
- خطای Timeout: وقتی سرور در بازه زمانی مشخص پاسخ نمی دهد.
رایج ترین خطاهای وب سرویس که باید بشناسید
حالا که می دانید دسته بندی کلی خطای وب سرویس چیست، بهتر است کمی دقیق تر روی همان کدهایی که در جدول دیدید مکث کنیم. شناخت دلیل دقیق هر کد، مسیر رفع خطای وب سرویس را خیلی کوتاه تر می کند.
خطای 400 (Bad Request)
این خطا معمولاً وقتی رخ می دهد که ساختار درخواست شما ایراد دارد؛ مثلاً JSON ناقص فرستاده اید یا پارامتری با نوع اشتباه (مثل ارسال متن به جای عدد) در بدنه درخواست قرار گرفته است.
راه حل: بدنه درخواست را با مستندات API مقایسه کنید و مطمئن شوید همه فیلدهای اجباری با فرمت درست ارسال شده اند.
خطای 401 (Unauthorized)
خطای 401 یعنی سرور نتوانسته هویت شما را تایید کند؛ معمولاً به این دلیل که API Key ارسال نشده، منقضی شده یا در هدر اشتباه قرار گرفته است.
راه حل: مقدار هدر Authorization را دوباره بررسی کنید و در صورت شک، یک کلید تازه از پنل خودتان بگیرید.
خطای 403 (Forbidden)
این خطا با 401 فرق دارد. اینجا هویت شما تایید شده، ولی اجازه دسترسی به آن منبع خاص را ندارید. معمولاً دلیلش محدودیت پلن، نقش کاربری یا آی پی غیرمجاز است.
راه حل: سطح دسترسی حساب و لیست آی پی های مجاز را در پنل بررسی کنید.
خطای 404 (Not Found)
یعنی آدرسی که درخواست را به آن فرستاده اید اصلاً وجود ندارد. این خطا معمولاً ناشی از تایپ اشتباه در مسیر (endpoint) یا استفاده از نسخه قدیمی API است.
راه حل: آدرس دقیق endpoint را از آخرین نسخه مستندات کپی کنید، نه از حافظه یا کدهای قبلی.
خطای 429 (Too Many Requests)
خطای 429 وقتی رخ می دهد که تعداد درخواست های شما در بازه زمانی مشخص از سقف مجاز عبور کرده است.
راه حل: به هدر Retry-After توجه کنید و به جای ارسال پیوسته، الگوی retry با فاصله زمانی افزایشی (backoff) پیاده سازی کنید.
خطای 500 (Internal Server Error)
این خطا یعنی مشکل اصلاً از سمت شما نیست؛ سرور در پردازش یک درخواست معتبر دچار مشکل داخلی و غیرمنتظره شده است.
راه حل: چند لحظه صبر کنید و دوباره تلاش کنید. اگر خطا همچنان ادامه داشت، لاگ درخواست را برای تیم پشتیبانی بفرستید.
خطای 503 (Service Unavailable)
معمولاً نشانه ای از بار زیاد روی سرور یا نگهداری (Maintenance) موقتی سیستم است و ارتباطی به کد شما ندارد.
راه حل: با فاصله زمانی مناسب دوباره درخواست را ارسال کنید. می توانید از پشتیبانی سرور زمان تکمیل فرایند نگهداری را جویا شوید و پس از آن مجددا تلاش کنید.
خطاهای اختصاصی وب سرویس پیامکی
اگر با یک وب سرویس پیامکی کار می کنید، علاوه بر کدهای استاندارد HTTP، معمولاً با چند خطای اختصاصی هم روبه رو می شوید که مخصوص همین نوع سرویس ها هستند:
- اعتبار ناکافی: موجودی حساب کافی برای ارسال پیامک وجود ندارد.
- خط ارسال نامعتبر: شماره خطی که در درخواست فرستاده اید ثبت یا فعال نشده است.
- شماره گیرنده اشتباه: فرمت شماره موبایل گیرنده نادرست یا ناقص وارد شده است.
- عدم تایید پترن: الگوی پیامک هنوز توسط تیم بررسی تایید نشده است.
- آی پی غیرمجاز: درخواست از آی پی مجاز تعریف شده در پنل ارسال نشده است.
- محدودیت ارسال: تعداد درخواست در بازه زمانی از سقف مجاز عبور کرده. این مورد دقیقاً همان منطق Rate Limit و خطای ۴۲۹ است که پیش تر توضیح دادیم.
روش عیب یابی گام به گام خطای وب سرویس
وقت آن رسیده که وارد فاز عملی شویم. اگر با یک خطا مواجه شده اید، این ترتیب را رعایت کنید تا سریع تر به ریشه مشکل برسید.
1.پاسخ خام سرور را کامل بخوانید
اولین کار این است که به جای فقط نگاه کردن به کد وضعیت، کل بدنه پاسخ را بخوانید. جزئیات ساختار Request و Response معمولاً همان چیزی است که دلیل دقیق خطا را نشان می دهد.
2.درخواست خود را در محیط دیگری تست کنید
می توانید در محیط Postman یا cURL پیش از هر شک به کد خودتان، همان درخواست را جدا از برنامه اصلی تست کنید. با آموزش Postman و آموزش cURL کار با دو ابزاری را یاد می گیرید که به شما اجازه می دهند بفهمید مشکل از کدهای شماست یا خود سرور.
3.هدرها را به دقت بررسی کنید
بسیاری از خطاهای 401 و 403 در واقع به دلیل هدر نادرست یا فراموش شده رخ می دهند. حتماً هدرهای HTTP درخواست خودتان را با مقادیر مورد انتظار مقایسه کنید.
4.لاگی های درخواست را چک کنید
اگر خطا در سمت سرور یا لایه اتصال است، لاگ سرور یا کلاینت معمولاً جزئیات بیشتری نسبت به پیام خطای ساده در اختیار می گذارد.
حتی در سیستم های قدیمی تر هم می توانید پارامتر LOG را به کانکشن استرینگ اضافه کنید تا اطلاعات تشخیصی اتصال در یک فایل ثبت شود و بعد از شکست اتصال، محل دقیق بروز مشکل را در آن فایل پیدا کنید. دقیقاً همین منطق در دیباگ وب سرویس های امروزی هم صادق است.
5.درخواست اصلاحی را در Sandbox تست کنید
پیش از اعمال تغییرات روی محیط اصلی، بهتر است ابتدا در محیط Sandbox درخواست را دوباره اجرا کنید تا بدون ریسک و بدون هزینه واقعی، مطمئن شوید مشکل برطرف شده است.
همیشه اول لاگ کنید و Retry با Backoff بزنید
دو عادت ساده می توانند بخش زیادی از دردسرهای شما با API را از بین ببرند:
- اول اینکه هر پاسخ API را – چه موفق چه ناموفق – لاگ کنید. با این کار وقتی به مشکلی برمی خورید، لازم نیست با حدس و گمان دیباگ را آغاز کنید، چون همه اطلاعات در دسترس شماست.
- دوم، پیاده سازی الگوی Retry با Backoff است. به جای تلاش فوری و پیوسته، هر بار فاصله زمانی بیشتری بین تلاش ها بگذارید. برای مثال در برابر خطاهای موقتی باید با تاخیر افزایشی دوباره تلاش کرد، چون تلاش فوری و پیوسته فقط باعث بدتر شدن وضعیت سرور یا محدودیت نرخ می شود. این روش مخصوصاً برای کدهای 429، 500 و 503 بسیار موثر است، اما توجه داشته باشید که فقط خطاهایی را باید دوباره تلاش کرد که احتمال خودبه خود برطرف شدن دارند.
چک لیست ۷ موردی قبل از تماس با پشتیبانی
قبل از اینکه وقت تیم پشتیبانی وب سرویس و خودتان را با یک تیکت بگیرید، این چک لیست را مرور کنید. شاید مشکل شما با یک بررسی دو دقیقه ای حل شود!
- کد خطا و پیام کامل پاسخ سرور را یادداشت کرده اید؟
- همان درخواست را در Postman یا cURL جدا تست کرده اید؟
- هدرهای Authorization و Content-Type را بررسی کرده اید؟
- اعتبار حساب و وضعیت خط ارسال را چک کرده اید؟
- فرمت شماره گیرنده و پارامترهای اجباری را دوباره کنترل کرده اید؟
- آی پی مجاز فعلی سرور شما با آی پی ثبت شده در پنل یکسان است؟
- تعداد درخواست های اخیر شما از سقف Rate Limit عبور نکرده است؟
اگر بعد از این هفت مورد هنوز خطا باقی ماند، احتمالاً مشکل از سمت سرور یا موضوعی خارج از دسترس شماست.
کی باید سراغ پشتیبانی فنی برویم؟
اگر همه مراحل بالا را رفتید و همچنان خطا برطرف نشد، بهتر است لاگ کامل درخواست و پاسخ را همراه خود داشته باشید و با تیم فنی تماس بگیرید.
این کار زمان بررسی را چند برابر کوتاه تر می کند. اگر تابه حال هنوز با وب سرویس پیامکی کار نکرده اید و می خواهید همین حالا مستندات و محیط تست را از نزدیک ببینید، می توانید در پیام رسان ثبت نام کنید و ۱۰۰ پیامک تست رایگان برای بررسی همین سناریوها بگیرید.
جمع بندی
در این مطلب خواندید که خطای وب سرویس چیست: یک پیام است که سرور برای راهنمایی شما می فرستد. اگر کد خطا را در سه دسته کاربر، سرور و شبکه دسته بندی کنید، از جدول کدها استفاده کنید و مسیر عیب یابی گام به گام را رعایت کنید، بخش بزرگی از خطاهای رایج در چند دقیقه برطرف می شود.
اگر باز هم مشکلی باقی ماند، لاگ کامل را همراه داشته باشید و از پشتیبانی فنی پیام رسان کمک بگیرید.
نام و شماره تماس خود را ثبت کنید تا کارشناسان ما در سریع‌ترین زمان با شما تماس بگیرند.
