خلاصه مقاله: Status Code یا کد وضعیت HTTP، عددی سه‌رقمی است که سرور پس از پردازش یک Request برای کلاینت ارسال می‌کند تا نتیجه درخواست را اعلام کند. این کدها مشخص می‌کنند که درخواست با موفقیت انجام شده، به تغییر مسیر نیاز دارد، خطایی در درخواست وجود دارد یا مشکلی در سمت سرور رخ داده است. در این مقاله با مفهوم Status Code، دسته‌بندی کدهای HTTP و رایج‌ترین کدهایی که هر توسعه‌دهنده باید بشناسد آشنا خواهید شد.

Status Code چیست؟

در مقاله HTTP دیدیم که مرورگر یا یک برنامه، درخواستی (Request) را برای سرور ارسال می‌کند و سرور پس از پردازش آن، پاسخی (Response) برمی‌گرداند.

اما مرورگر چگونه متوجه می‌شود که درخواست با موفقیت انجام شده است؟ از کجا می‌فهمد صفحه موردنظر پیدا نشده یا خطایی در سرور رخ داده است؟

پاسخ این سؤال در مفهومی به نام Status Code قرار دارد.

Status Code یک عدد سه‌رقمی است که سرور همراه با Response ارسال می‌کند تا نتیجه پردازش Request را به کلاینت اعلام کند.

به زبان ساده، Status Code مانند یک پیام کوتاه است که به مرورگر می‌گوید درخواست موفق بوده، باید دوباره تلاش کند یا مشکلی به وجود آمده است.

چرا Status Code اهمیت دارد؟

فرض کنید مرورگر پس از ارسال یک Request فقط داده دریافت می‌کرد و هیچ اطلاعی از وضعیت درخواست نداشت.

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

Status Code این مشکل را حل می‌کند و نتیجه هر درخواست را به شکلی استاندارد اعلام می‌کند.

به همین دلیل، تمام مرورگرها، APIها و ابزارهای توسعه وب از این کدها استفاده می‌کنند.

یک مثال ساده

فرض کنید سفارشی را در یک فروشگاه اینترنتی ثبت می‌کنید.

پس از ثبت سفارش، فروشگاه یکی از پیام‌های زیر را به شما نمایش می‌دهد:

سفارش با موفقیت ثبت شد.
محصول موردنظر موجود نیست.
ابتدا باید وارد حساب کاربری شوید.
در حال حاضر مشکلی در سیستم وجود دارد.

Status Code نیز دقیقاً همین نقش را در ارتباط بین کلاینت و سرور ایفا می‌کند و نتیجه درخواست را به‌صورت استاندارد اعلام می‌کند.

Status Code چگونه کار می‌کند؟

هر بار که یک Request به سرور ارسال می‌شود، سرور ابتدا آن را بررسی و پردازش می‌کند.

پس از پایان پردازش، علاوه بر داده‌های Response، یک Status Code نیز ارسال می‌شود.

مرورگر یا برنامه با بررسی این کد تصمیم می‌گیرد چه کاری انجام دهد.

برای مثال، ممکن است صفحه را نمایش دهد، کاربر را به صفحه دیگری هدایت کند یا یک پیام خطا نشان دهد.

آیا همه Status Codeها خطا هستند؟

خیر.

یکی از رایج‌ترین برداشت‌های اشتباه این است که Status Code فقط برای نمایش خطاها استفاده می‌شود.

در واقع، بسیاری از Status Codeها نشان‌دهنده موفقیت درخواست هستند و اصلاً به معنای وجود مشکل نیستند.

برای مثال، معروف‌ترین Status Code یعنی 200 OK به این معناست که درخواست با موفقیت انجام شده است.

دسته‌بندی Status Codeها

تمام Status Codeهای HTTP در پنج دسته اصلی قرار می‌گیرند.

هر دسته با رقم اول کد مشخص می‌شود و مفهوم کلی متفاوتی دارد.

1xx : پیام‌های اطلاع‌رسانی
2xx : درخواست با موفقیت انجام شده است.
3xx : برای تکمیل درخواست باید تغییر مسیر انجام شود.
4xx : مشکلی در درخواست ارسال‌شده توسط کلاینت وجود دارد.
5xx : خطا در سمت سرور رخ داده است.

در ادامه هر یک از این گروه‌ها را بررسی می‌کنیم.

کدهای 1xx

کدهای گروه 1xx برای اطلاع‌رسانی استفاده می‌شوند.

این کدها نشان می‌دهند که سرور درخواست را دریافت کرده است و پردازش آن همچنان ادامه دارد.

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

کدهای 2xx

کدهای گروه 2xx نشان‌دهنده موفقیت هستند.

وقتی درخواست بدون مشکل انجام شود، سرور یکی از کدهای این گروه را برمی‌گرداند.

معروف‌ترین عضو این گروه، 200 OK است که تقریباً تمام توسعه‌دهندگان وب با آن آشنا هستند.

کدهای موفقیت فقط به دریافت صفحات وب محدود نمی‌شوند و هنگام ایجاد، ویرایش یا حذف اطلاعات در APIها نیز استفاده می‌شوند.

کدهای 3xx

گاهی منبع موردنظر به آدرس دیگری منتقل شده است.

در چنین شرایطی، سرور یکی از کدهای گروه 3xx را ارسال می‌کند.

مرورگر با دریافت این کد متوجه می‌شود که باید برای دریافت منبع به آدرس دیگری مراجعه کند.

این گروه از Status Codeها در مدیریت تغییر آدرس صفحات و ریدایرکت‌ها اهمیت زیادی دارند.

کدهای 4xx

اگر مشکلی در Request وجود داشته باشد، معمولاً یکی از کدهای گروه 4xx برگردانده می‌شود.

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

خطاهای این گروه معمولاً به درخواست کلاینت مربوط هستند، نه به عملکرد سرور.

کدهای 5xx

برخلاف گروه قبلی، کدهای 5xx نشان می‌دهند که مشکل در سمت سرور رخ داده است.

در این حالت، Request معمولاً به‌درستی ارسال شده است، اما سرور به هر دلیلی نتوانسته آن را پردازش کند.

یکی از شناخته‌شده‌ترین اعضای این گروه، 500 Internal Server Error است.

در بخش بعدی مقاله، معروف‌ترین Status Codeهای HTTP مانند 200، 201، 301، 302، 400، 401، 403، 404 و 500 را به‌صورت کامل بررسی می‌کنیم و می‌بینیم هر کدام در چه شرایطی استفاده می‌شوند.

200 OK

کد 200 OK رایج‌ترین Status Code در HTTP است.

این کد نشان می‌دهد که درخواست با موفقیت پردازش شده و سرور پاسخ موردنظر را بدون مشکل به کلاینت ارسال کرده است.

برای مثال، زمانی که صفحه اصلی یک وب‌سایت را باز می‌کنید و همه‌چیز به‌درستی نمایش داده می‌شود، معمولاً پاسخ سرور با کد 200 همراه است.

در REST API نیز دریافت موفق اطلاعات معمولاً با Status Code 200 انجام می‌شود.

201 Created

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

برای مثال، اگر کاربر یک حساب کاربری جدید ایجاد کند یا محصول جدیدی در یک فروشگاه اینترنتی ثبت شود، سرور معمولاً کد 201 را برمی‌گرداند.

این Status Code بیشتر در درخواست‌های POST مشاهده می‌شود.

204 No Content

گاهی سرور درخواست را با موفقیت انجام می‌دهد، اما نیازی به ارسال هیچ محتوایی در Response وجود ندارد.

در چنین شرایطی از 204 No Content استفاده می‌شود.

برای مثال، پس از حذف موفق یک رکورد در یک API، ممکن است تنها همین Status Code به کلاینت ارسال شود.

301 Moved Permanently

کد 301 Moved Permanently نشان می‌دهد که منبع موردنظر برای همیشه به آدرس جدیدی منتقل شده است.

مرورگر و موتورهای جستجو با دریافت این کد متوجه می‌شوند که از این پس باید از URL جدید استفاده کنند.

به همین دلیل، هنگام تغییر دائمی آدرس صفحات یک وب‌سایت معمولاً از ریدایرکت 301 استفاده می‌شود.

302 Found

کد 302 Found نیز برای تغییر مسیر استفاده می‌شود، اما برخلاف 301، این انتقال دائمی نیست.

سرور به مرورگر اعلام می‌کند که فعلاً باید درخواست را از آدرس دیگری دریافت کند، اما ممکن است در آینده دوباره از آدرس اصلی استفاده شود.

این کد معمولاً برای تغییر مسیرهای موقت به کار می‌رود.

400 Bad Request

کد 400 Bad Request نشان می‌دهد که درخواست ارسال‌شده توسط کلاینت معتبر نیست.

ممکن است بخشی از اطلاعات اشتباه باشد یا ساختار Request با آنچه سرور انتظار دارد مطابقت نداشته باشد.

برای مثال، اگر یک API انتظار دریافت اطلاعات مشخصی را داشته باشد اما داده‌های ناقص یا نامعتبر دریافت کند، احتمال دارد پاسخ 400 ارسال شود.

401 Unauthorized

کد 401 Unauthorized زمانی برگردانده می‌شود که کاربر برای دسترسی به منبع موردنظر احراز هویت نشده باشد.

برای مثال، اگر یک API فقط کاربران واردشده را بپذیرد و کاربر بدون ورود درخواست ارسال کند، معمولاً پاسخ 401 دریافت خواهد کرد.

این کد به این معنا نیست که کاربر هرگز اجازه دسترسی ندارد، بلکه ابتدا باید هویت خود را اثبات کند.

403 Forbidden

کد 403 Forbidden با 401 تفاوت دارد.

در این حالت، سرور هویت کاربر را می‌شناسد، اما اجازه دسترسی به منبع موردنظر را به او نمی‌دهد.

برای مثال، اگر یک کاربر عادی بخواهد وارد بخش مدیریت سایت شود، ممکن است پاسخ 403 دریافت کند.

404 Not Found

کد 404 Not Found یکی از شناخته‌شده‌ترین Status Codeهای اینترنت است.

این کد نشان می‌دهد که سرور درخواست را دریافت کرده، اما منبع موردنظر پیدا نشده است.

برای مثال، اگر آدرس صفحه‌ای را اشتباه وارد کنید یا صفحه حذف شده باشد، معمولاً با خطای 404 مواجه خواهید شد.

وجود این کد لزوماً به معنای وجود مشکل در سرور نیست؛ تنها نشان می‌دهد که منبع درخواست‌شده وجود ندارد.

405 Method Not Allowed

کد 405 Method Not Allowed زمانی برگردانده می‌شود که URL وجود داشته باشد، اما متد HTTP استفاده‌شده مجاز نباشد.

برای مثال، ممکن است یک Endpoint فقط درخواست‌های GET را بپذیرد، اما کلاینت درخواست POST ارسال کند.

در این حالت، سرور معمولاً پاسخ 405 را ارسال می‌کند.

500 Internal Server Error

کد 500 Internal Server Error یکی از رایج‌ترین خطاهای سمت سرور است.

این کد نشان می‌دهد که هنگام پردازش Request، مشکلی در سرور رخ داده و درخواست قابل انجام نبوده است.

در پروژه‌های واقعی، خطاهای برنامه‌نویسی، مشکلات پایگاه داده یا تنظیمات نادرست سرور می‌توانند باعث ایجاد این Status Code شوند.

502 Bad Gateway

کد 502 Bad Gateway معمولاً در معماری‌هایی دیده می‌شود که بین کاربر و سرور اصلی، یک سرور واسط مانند Reverse Proxy یا Load Balancer قرار دارد.

اگر سرور واسط نتواند پاسخ معتبری از سرور اصلی دریافت کند، ممکن است پاسخ 502 را به کلاینت ارسال کند.

503 Service Unavailable

کد 503 Service Unavailable نشان می‌دهد که سرور در حال حاضر قادر به پاسخ‌گویی نیست.

این وضعیت ممکن است به دلیل انجام عملیات نگهداری، به‌روزرسانی یا افزایش بیش از حد بار سرور ایجاد شود.

برخلاف خطای 500، این وضعیت معمولاً موقتی است و پس از مدتی برطرف می‌شود.

کدام Status Codeها را باید بیشتر بشناسیم؟

اگرچه HTTP ده‌ها Status Code مختلف دارد، اما در توسعه روزمره معمولاً تعداد محدودی از آن‌ها بیشتر استفاده می‌شوند.

200 OK
201 Created
204 No Content
301 Moved Permanently
302 Found
400 Bad Request
401 Unauthorized
403 Forbidden
404 Not Found
405 Method Not Allowed
500 Internal Server Error
502 Bad Gateway
503 Service Unavailable

در بخش پایانی مقاله بررسی می‌کنیم چرا Status Codeها برای توسعه وب و REST API اهمیت دارند، اشتباهات رایج در استفاده از آن‌ها چیست و هر برنامه‌نویس هنگام طراحی API باید به چه نکاتی توجه کند.

چرا Status Codeها اهمیت دارند؟

Status Codeها یکی از مهم‌ترین بخش‌های پروتکل HTTP هستند و باعث می‌شوند کلاینت و سرور بتوانند بدون ابهام با یکدیگر ارتباط برقرار کنند.

اگر سرور فقط داده ارسال می‌کرد و هیچ Status Codeای وجود نداشت، مرورگر یا برنامه نمی‌توانست تشخیص دهد که درخواست با موفقیت انجام شده، کاربر مجوز دسترسی ندارد یا مشکلی در سرور رخ داده است.

به همین دلیل، تقریباً تمام وب‌سایت‌ها، REST APIها، اپلیکیشن‌های موبایل و سرویس‌های تحت وب از این کدها استفاده می‌کنند.

Status Codeها در REST API چه نقشی دارند؟

در REST API، Status Codeها اهمیت ویژه‌ای دارند، زیرا کلاینت معمولاً بر اساس همین کدها تصمیم می‌گیرد چه کاری انجام دهد.

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

به همین دلیل، انتخاب صحیح Status Codeها یکی از اصول طراحی یک REST API استاندارد محسوب می‌شود.

آیا همیشه باید از Status Code مناسب استفاده کرد؟

بله.

گاهی در برخی پروژه‌ها مشاهده می‌شود که سرور برای تمام درخواست‌ها، حتی در صورت بروز خطا، فقط کد 200 را برمی‌گرداند و جزئیات خطا را در بدنه Response قرار می‌دهد.

این کار برخلاف استاندارد HTTP است و باعث می‌شود مرورگرها، ابزارهای توسعه و سایر سرویس‌ها نتوانند وضعیت واقعی درخواست را به‌درستی تشخیص دهند.

بهتر است برای هر وضعیت، مناسب‌ترین Status Code انتخاب شود تا رفتار سیستم قابل‌پیش‌بینی و استاندارد باشد.

اشتباهات رایج در استفاده از Status Codeها

برخی اشتباهات در پروژه‌های وب و APIها بسیار رایج هستند.

برگرداندن 200 برای درخواست‌هایی که با خطا مواجه شده‌اند.
استفاده از 500 برای خطاهایی که در واقع مربوط به کلاینت هستند.
استفاده نادرست از 401 و 403 به جای یکدیگر.
ارسال پیام‌های مبهم بدون استفاده از Status Code مناسب.
نادیده گرفتن ریدایرکت‌های استاندارد مانند 301 هنگام تغییر دائمی آدرس صفحات.

رعایت استانداردهای HTTP باعث می‌شود توسعه، نگهداری و عیب‌یابی پروژه آسان‌تر شود.

Status Codeها را چگونه مشاهده کنیم؟

اگر از مرورگرهای مدرن مانند Chrome یا Firefox استفاده کنید، می‌توانید Status Code هر درخواست را مشاهده کنید.

برای این کار کافی است ابزار Developer Tools را باز کرده و به بخش Network بروید.

در این بخش، تمام درخواست‌های ارسال‌شده به همراه اطلاعاتی مانند URL، متد HTTP، زمان پاسخ و Status Code نمایش داده می‌شوند.

این قابلیت یکی از مهم‌ترین ابزارهای توسعه‌دهندگان برای بررسی و عیب‌یابی وب‌سایت‌ها و APIها است.

Status Codeها در Django

در Django نیز تمام Responseها دارای Status Code هستند.

اگر View با موفقیت اجرا شود، معمولاً پاسخ با کد 200 ارسال می‌شود.

در صورت وجود نداشتن مسیر موردنظر، Django به‌طور پیش‌فرض پاسخ 404 برمی‌گرداند و اگر خطایی در اجرای برنامه رخ دهد، معمولاً پاسخ 500 ارسال می‌شود.

همچنین هنگام توسعه REST API با Django REST Framework، توسعه‌دهنده می‌تواند برای هر Response، Status Code مناسب را به‌صورت صریح تعیین کند تا رفتار API مطابق استانداردهای HTTP باشد.

جمع‌بندی

Status Code یا کد وضعیت HTTP، عددی سه‌رقمی است که سرور همراه با Response برای کلاینت ارسال می‌کند تا نتیجه پردازش یک Request را اعلام کند.

این کدها در پنج گروه اصلی شامل 1xx، 2xx، 3xx، 4xx و 5xx دسته‌بندی می‌شوند و هر گروه مفهوم مشخصی دارد؛ از اطلاع‌رسانی و موفقیت گرفته تا تغییر مسیر، خطاهای سمت کلاینت و خطاهای سمت سرور.

آشنایی با رایج‌ترین Status Codeها مانند 200، 201، 301، 400، 401، 403، 404 و 500 برای هر توسعه‌دهنده وب ضروری است و به طراحی APIهای استاندارد، عیب‌یابی سریع‌تر و درک بهتر عملکرد HTTP کمک می‌کند.

سؤالات متداول