اگر کد ۴۰۴ یا ۵۰۳ روی صفحه نمایش تان ظاهر شد، خوب است بدانید که به این اعداد Status Code می گویند. Status Code چیست؟ یک عدد سه رقمی که سرور در پاسخ به هر درخواست HTTP برمی گرداند و نتیجه دقیق آن درخواست را نشان می دهد.
حالا به نظرتان درخواست شما موفق بوده؟ رد شده؟ مشکل از شماست یا از سرور؟ در ادامه همه کدهای پرکاربرد را به زبان ساده توضیح می دهیم؛ طوری که دیگر مجبور نباشید هر بار برای یک عدد سه رقمی به گوگل پناه ببرید.
Status Code دقیقاً چیست؟
هر بار که یک کلاینت (مرورگر، اپلیکیشن موبایل یا کدی که برای فراخوانی API نوشته اید) درخواستی به سرور می فرستد، سرور موظف است پاسخی را برگرداند. این پاسخ همیشه شامل یک عدد سه رقمی به نام کد وضعیت یا Status Code است که مستقل از محتوای پاسخ، وضعیت کلی آن را مشخص می کند.
به عبارت دیگر، کد وضعیت همان چیزی است که به رابطه Request و Response معنا می دهد: شما درخواستی می فرستید (Request) و سرور با یک بدنه پاسخ (Body) به همراه یک کد وضعیت جوابتان را می دهد (Response). بدنه پاسخ ممکن است پیچیده و طولانی باشد، ولی کد وضعیت همیشه سه رقم است.
ارقام Status Code چه معنایی دارند؟
شاید برایتان سوال شده باشد که تفاوت میان ارقام Status Code چیست و آیا اصلاً با هم فرقی دارند؟ در پاسخ باید بگوییم به طور کلی:
- رقم اول: دسته کلی پاسخ را مشخص می کند؛
- دو رقم بعدی: جزئیات بیشتری اضافه می کنند.
دقیقاً به همین دلیل است که در دنیای برنامه نویسی کدهای وضعیت را در دسته بندی 1xx تا 5xx قرار می دهند.
جدول دسته بندی کدهای وضعیت
قبل از اینکه سراغ معنی تک تک کدها برویم، بهتر است یک نقشه کلی از پنج دسته اصلی داشته باشید:
| دسته | محدوده عددی | معنی کلی |
|---|---|---|
| اطلاع رسانی | 100 تا 199 | درخواست دریافت شده و پردازش در حال انجام است. |
| موفقیت | 200 تا 299 | درخواست با موفقیت پردازش شده است. |
| ریدایرکت | 300 تا 399 | منبع جای دیگری قرار دارد. باید اقدامات دیگری انجام دهید. |
| خطای کلاینت | 400 تا 499 | مشکل از درخواستی است که شما فرستاده اید. |
| خطای سرور | 500 تا 599 | مشکل از سمت سرور و زیرساخت آن است. |
دسته اول (1xx) را در کار روزمره برنامه نویسی تقریباً هیچ وقت نمی بینید، چون این کدها موقتی هستند و مرورگر یا کلاینت آن ها را به شما نشان نمی دهد. ولی باید بدانید معنی چهار دسته دیگر Status Code چیست، چون در دنیای برنامه نویسی با آن ها زیاد مواجه خواهید شد.
مهم ترین کدهای وضعیت که باید بشناسید
حالا وقت آن رسیده که سراغ کدهای واقعی برویم. همان هایی که در لاگ سرور، Postman یا کنسول مرورگر مدام می بینید.
کدهای موفقیت (2xx)
این دسته بوی موفقیت می دهند. بیایید ببینیم مفهوم کدهای دومین دسته Status Code چیست:
200 OK
این کد نشان می دهد که درخواست شما با موفقیت پردازش شده و سرور دقیقاً همان چیزی را که خواسته بودید برگردانده است. 200 رایج ترین کدی است که در یک سرویس سالم می بینید و معمولاً نیاز به هیچ اقدامی ندارد.
201 Created
این کد یعنی منبع جدیدی با موفقیت ساخته شده و معمولاً پاسخ استاندارد یک درخواست POST است. اگر بعد از ثبت یک آیتم جدید این کد را نگرفتید، احتمالاً چیزی در فرایند ذخیره سازی ناقص مانده است.
به نقل از MDN Web Docs
The request succeeded, and a new resource was created as a result.
ترجمه: درخواست با موفقیت انجام شده و در نتیجهٔ آن، منبع جدیدی ایجاد شده است.
204 No Content
درخواست موفق بوده، ولی سرور چیزی برای برگرداندن در بدنه پاسخ ندارد. مثلاً بعد از یک درخواست DELETE موفق. اگر کد ۲۰۴ گرفتید دیگر نباید منتظر چیزی از سمت سرور باشید.
کدهای ریدایرکت (3xx)
این کدها نیز موارد متعددی دارند که مهم ترینشان را معرفی می کنیم:
301 Moved Permanently
یعنی منبع برای همیشه به آدرس دیگری منتقل شده است. کلاینت ها و موتورهای جست وجو باید از این به بعد آدرس جدید را استفاده کنند.
302 Found
302 هم یک کد ریدایرکت است، ولی موقتی. به معنای اینکه منبع فعلاً جای دیگری است، ولی آدرس اصلی همچنان معتبر باقی می ماند. اشتباه گرفتن ۳۰۱ با ۳۰۲ یکی از رایج ترین خطاهای برنامه نویسان تازه کار است.
کدهای خطای کلاینت (4xx)
اگر مشکل از سمت شما باشد نه سرور، آنوقت احتمالاً یکی از کدهای زیر را دریافت کنید:
400 Bad Request
این کد یعنی ساختار درخواست شما ایراد دارد، پارامتری ناقص است، JSON به شکل نادرستی ارسال شده یا فرمت داده اشتباه است. وقتی این کد را دریافت کردید باید بدنه درخواست تان را دوباره با دقت بیشتری بررسی کنید.
401 Unauthorized
کد 401 یعنی احراز هویت انجام نشده یا نامعتبر است. یعنی سرور اصلاً نمی داند شما کی هستید. برای جزئیات کامل این کد و روش رفع آن، خطای 401 Unauthorized را جداگانه بررسی کرده ایم.
403 Forbidden
برخلاف ۴۰۱، این بار سرور شما را می شناسد ولی اجازه دسترسی به این منبع را نمی دهد. این کد معمولاً به سطح دسترسی، توکن یا IP شما مرتبط است.
404 Not Found
منبع درخواستی روی سرور وجود ندارد. این کد یکی از معروف ترین کدهای خطای HTTP در دنیای وب است که هم برای کاربران و برنامه نویسان زیاد اتفاق می افتد.
405 Method Not Allowed
کد 405 به این معناست که متد HTTP که استفاده کرده اید (مثلاً GET به جای POST) برای این آدرس مجاز نیست. اگر با فهم بهتر این کد باید متدهای HTTP را بشناسید.
429 Too Many Requests
تعداد درخواست های شما در بازه زمانی مشخص از سقف مجاز گذشته است. برای فهم دقیق این محدودیت و روش مدیریت آن مقاله Rate Limit و خطای ۴۲۹ را جداگانه مطالعه کنید. جزئیات فنی بیشتر هم در مطلب 429 Too Many Requests توضیح داده شده اند.
کدهای خطای سرور (5xx)
گاهی مشکل از کلاینت نیست و سرور با چالشی دست وپنجه نرم می کند. در این مواقع با کدهای 5xx مواجه می شوید.
500 Internal Server Error
یک خطای عمومی و نامشخص در سمت سرور رخ داده است. معمولاً باگی در کد بک اند یا خطایی غیرمنتظره در پردازش درخواست ارسال کد 500 می شود.
502 Bad Gateway
سروری که به عنوان واسط یا پروکسی عمل می کند، پاسخ نامعتبری از سرور اصلی دریافت کرده است. این کد هم بیشتر به مشکلات زیرساختی بین چند سرویس مرتبط است و مانند 402 زیاد توسط کاربران مشاهده می شود. مخصوصاً برای ما ایرانی ها که مدام از پروکسی استفاده می کنیم.
503 Service Unavailable
سرور (معمولاً به دلیل بار زیاد یا تعمیرات موقت) فعلاً قادر به پاسخگویی نیست. این کد معمولاً موقتی است و با گذشت زمان کوتاهی برطرف می شود.
مشکل از من است یا از سرور؟
این سوال را هر برنامه نویسی هنگام دیدن یک خطا از خودش می پرسد. حال که می دانید Status Code چیست، احتمالاً متوجه شده اید که برای پاسخ به آن فقط کافی است به رقم اول کد نگاه کنید.
- اگر کد در دسته خطای کلاینت (4xx) قرار دارد، یعنی درخواست شما ایراد دارد. پارامتر ناقص، توکن نامعتبر یا دسترسی محدود می توانند از دلایل اصلی باشند.
- اگر با خطای سرور (5xx) مواجه شدید، مشکل کاملاً از زیرساخت یا کد سمت سرور است و معمولاً کاری از دست شما ساخته نیست جز صبر کردن یا اطلاع دادن به تیم پشتیبانی.
برای بررسی این که دقیقاً چه چیزی در درخواست تان اشتباه بوده، بهتر است همیشه پاسخ کامل سرور را زیر ذره بین بگذارید. در این مسیر آموزش Postman کمک زیادی می کند تا هدر، بدنه و کد وضعیت را در یک صفحه کنار هم ببینید.
به نقل از Postman
Status codes alone don’t provide enough context for debugging.
ترجمه: کدهای وضعیت به‌تنهایی اطلاعات کافی برای عیب‌یابی در اختیار شما نمی‌گذارند.
کدهایی که در وب سرویس پیامکی بیشتر می بینید
ازآنجایی که خیلی از کاربران پیام رسان با وب سرویس پیامکی ما سروکار دارند، اجازه دهید چند کد معروف که در وب سرویس های پیامکی دیده می شوند را به عنوان مثال بررسی کنیم و ببینیم دلیل ارسال آن ها چیست.
- کد 401: یعنی API Key ارسالی تان اشتباه یا منقضی است.
- کد 403: درخواست شما از یک IP ارسال شده که در پنل پیامکی غیرمجاز است.
- کد 429: تعداد درخواست های ارسالی در بازه زمانی مشخص بیش از سقف مجاز بوده است.
- کد 400: یکی از فیلدهای ضروری مثل شماره گیرنده یا متن پیامک در درخواست جا افتاده است.
تا به اینجای مقاله تقریباً به طور کامل فهمیده اید Status Code چیست. از این به بعد می خواهیم چند ریزه کاری مهم را توضیح دهیم.
آیا کد 200 یعنی پیامک رسیده؟
این باور یکی از رایج ترین سوءتفاهم های برنامه نویسانی است که تازه با وب سرویس پیامکی کار می کنند. دریافت کد 200 فقط یعنی سرور درخواست شما را با موفقیت پذیرفته و در صف پردازش قرار داده است، نه اینکه پیامک واقعاً به گوشی گیرنده رسیده باشد!
تحویل نهایی پیامک یک فرایند جداست که معمولاً کمی بعد از ارسال اتفاق می افتد و باید از طریق متد جداگانه ای بررسی شود. برای اطمینان از این که پیامک واقعاً به دست گیرنده رسیده، باید سراغ گزارش دلیوری پیامک بروید.
چرا کدهای وضعیت در سئو اهمیت دارند؟
کدهای وضعیت فقط برای برنامه نویسان مهم نیستند. سئوکارها نیز باید کدهای خطا HTTP را بشناسند. می پرسید چرا؟ اجازه دهید با دو مثال توضیح دهیم:
- استفاده درست از 301 هنگام تغییر آدرس صفحات باعث می شود اعتبار سئوی صفحه قدیمی به آدرس جدید منتقل شود، بدون اینکه رتبه سایت در نتایج جست وجو آسیب ببیند.
- در مقابل، وجود تعداد زیاد 404 روی سایت می تواند نشانه ای از تجربه کاربری ضعیف برای موتورهای جست وجو باشد و در بلندمدت روی خزش و ایندکس سایت اثر منفی بگذارد.
فقط بادی پاسخ را چک نکنید!
یکی از بزرگترین اشتباهاتی که برنامه نویسان تازه کار مرتکب می شوند این است که فقط به محتوای بدنه پاسخ نگاه می کنند و کد وضعیت را نادیده می گیرند. مشکل اینجاست که بعضی سرورها حتی هنگام بروز خطا هم یک بدنه پاسخ شبیه به حالت موفق برمی گردانند.
بنابراین همیشه قبل از پردازش داده، اول کد وضعیت را چک کنید. اگر کد در دسته موفقیت (2xx) نبود، اصلاً اگر وارد پردازش بدنه پاسخ نشدید هم عیبی ندارد!
چه زمانی در مواجهه با Status Code باید Retry کنیم؟
ارسال دوباره درخواست خیلی وقت ها مثل کوبیدن سر روی دیوار است و هیچ تاثیری روی نتیجه نهایی ندارد! با این حال در دو موقعیت خاص می توانید Retry کنید و انتظار داشته باشید اتفاقات بهتری بیفتد:
- کد 500 و 503: این خطاها معمولاً موقتی هستند. اگر می خواهید از Retry نتیجه بگیرید، بهترین روش استفاده از الگوی Exponential Backoff است. یعنی بین هر تلاش، زمان انتظار را دو یا سه برابر کنید (مثلاً ۱ ثانیه، بعد ۲ ثانیه، بعد ۴ ثانیه) تا فشار الکی به سرور وارد نشود.
- کد 429: در این حالت بهتر است به هدر Retry-After که سرور برمی گرداند نگاه کنید و دقیقاً همان قدر برای ارسال دوباره درخواست صبر کنید، نه بیشتر نه کمتر!
جمع بندی
با خواندن این مقاله حالا می دانید Status Code چیست: وضعیت همان زبان مشترکی است که سرور و کلاینت با آن درباره نتیجه هر درخواست صحبت می کنند. یادگیری به شما کمک می کند از همان لحظه، دقیقاً بدانید مشکل از کجاست.
اگر در حال توسعه یا اتصال به یک سرویس پیامکی هستید و می خواهید همین حالا کدهای وضعیت واقعی را در محیط عملی تست کنید، پیشنهاد می کنیم فرم زیر رو پر کنید تا کارشناسان ما با شما تماس بگیرند تا راهنمایی کنند.
نام و شماره تماس خود را ثبت کنید تا کارشناسان ما در سریع‌ترین زمان با شما تماس بگیرند.
