راهنمای جامع کد های وضعیت HTTP

کدهای وضعیت HTTP (Status Code) پاسخ‌هایی هستند که سرور به درخواست‌های ارسالی از سمت کلاینت (مانند مرورگر یا برنامه) ارائه می‌دهد. این کدها اطلاعاتی درباره وضعیت درخواست، موفقیت یا شکست آن و همچنین اقدامات لازم برای کلاینت فراهم می‌کنند. کدهای وضعیت HTTP به پنج دسته اصلی تقسیم می‌شوند که هر یک با یک عدد سه‌رقمی مشخص شده و با یک پیام متنی همراه است. این مقاله به بررسی جامع تمامی کدهای وضعیت HTTP، کاربردها، مشکلات رایج و راه‌حل‌های مرتبط با آن‌ها می‌پردازد.

دسته‌بندی کدهای وضعیت HTTP

کدهای وضعیت HTTP به پنج دسته اصلی تقسیم می‌شوند:

• 1xx (اطلاعاتی – Informational): نشان‌دهنده پاسخ‌های موقت هستند که فرآیند درخواست هنوز ادامه دارد.
• 2xx (موفقیت – Success): نشان‌دهنده موفقیت‌آمیز بودن درخواست کلاینت.
• 3xx (تغییر مسیر – Redirection): نشان‌دهنده نیاز به اقدام اضافی از سمت کلاینت برای تکمیل درخواست.
• 4xx (خطای کلاینت – Client Error): نشان‌دهنده خطا در درخواست ارسالی از سمت کاربر.
• 5xx (خطای سرور – Server Error): نشان‌دهنده خطا در سمت سرور هنگام پردازش درخواست.

در ادامه، هر دسته به همراه کدهای مربوطه، توضیحات، مشکلات رایج و راه‌حل‌ها بررسی می‌شود.

کدهای وضعیت http سری 1xx؛ پاسخ‌های اطلاعاتی 

• 100 ادامه (Continue): این پاسخ موقت نشان می‌دهد که مشتری باید درخواست را ادامه دهد یا اگر درخواست قبلاً به پایان رسیده است، این پاسخ را نادیده بگیرد.
• 101 تغییر پروتکل (Switching Protocols): این کد در پاسخ به سرآیند درخواست ارتقاء (Upgrade request header) از طرف مشتری ارسال می‌شود و پروتکلی را نشان می‌دهد که سرور به آن تغییر می‌دهد.
• 102 در حال پردازش (Processing): این کد در زمینه‌های WebDAV استفاده می‌شد تا نشان دهد که یک درخواست توسط سرور دریافت شده است، اما در زمان پاسخ، هیچ وضعیتی در دسترس نبوده است.
• 103 راهنمایی‌های اولیه (Early Hints): این کد وضعیت عمدتاً برای استفاده با سرآیند Link در نظر گرفته شده است و به عامل کاربر اجازه می‌دهد تا بارگیری منابع را در حالی که سرور در حال آماده‌سازی پاسخ است، شروع کند یا به مبدأیی که صفحه به منابع آن نیاز خواهد داشت، از قبل متصل شود.

کدهای وضعیت http سری 2xx؛ پاسخ‌های موفق

• 200 تأیید (OK): درخواست با موفقیت انجام شد. نتیجه و معنای “موفقیت” بسته به نوع درخواست HTTP متفاوت است:

1. GET: منبع مورد نظر دریافت و در بدنه پیام منتقل شده است.
2. HEAD: هدرهای مربوط به منبع، بدون هیچ بدنه پیامی در پاسخ گنجانده شده‌اند.
3. PUT یا POST: منبعی که نتیجه عملکرد را شرح می‌دهد، در بدنه پیام منتقل می‌شود.
4. TRACE: بدنه پیام حاوی درخواستی است که سرور آن را دریافت کرده است.

• 201 ایجاد شد (Created): درخواست با موفقیت انجام شده و منبع جدیدی در نتیجه آن ایجاد شده است. این پاسخ معمولاً پس از درخواست‌های POST یا برخی درخواست‌های PUT ارسال می‌شود.
• 202 پذیرفته شد (Accepted): درخواست دریافت شده اما هنوز اقدامی روی آن صورت نگرفته است. این پاسخ قطعی نیست، زیرا در HTTP راهی برای ارسال پاسخ غیرهمزمان بعدی که نشان‌دهنده نتیجه درخواست باشد، وجود ندارد. این وضعیت برای مواردی در نظر گرفته شده است که پردازش درخواست توسط فرآیند یا سرور دیگری انجام می‌شود یا برای پردازش دسته‌ای کاربرد دارد.
• 203 اطلاعات غیر معتبر (Non-Authoritative Information): این کد پاسخ به این معنی است که فراداده‌های برگشتی دقیقاً مشابه فراداده‌های موجود در سرور اصلی نیستند، بلکه از یک کپی محلی یا شخص ثالث جمع‌آوری شده‌اند. این وضعیت بیشتر برای آینه‌ها یا نسخه‌های پشتیبان از یک منبع دیگر استفاده می‌شود. به جز این مورد خاص، پاسخ 200 OK بر این وضعیت ترجیح داده می‌شود.
• 204 بدون محتوا (No Content): درخواست موفقیت‌آمیز بوده اما پاسخی برای بازگشت وجود ندارد. در درخواست‌های DELETE یا PATCH که نیازی به بازگشت داده ندارند.
• 205 بازنشانی محتوا (Reset Content): به مرورگر کاربر دستور می‌دهد سند ارسالی این درخواست را بازنشانی کند.
• 206 محتوای جزئی (Partial Content): این کد پاسخ در پاسخ به یک درخواست محدوده (range request) استفاده می‌شود، زمانی که کاربر بخشی یا بخش‌هایی از یک منبع را درخواست کرده باشد.

کد های وضعیت http سری 3xx؛ پیام‌های تغییر مسیر

• 301 انتقال دائمی (Moved Permanently):نشانی اینترنتی منبع درخواست شده به طور دائم تغییر کرده است. نشانی اینترنتی جدید در پاسخ ارائه شده است.
• 302 یافت شد (Found): این کد پاسخ نشان می‌دهد که نشانی یکنواخت منبع درخواست شده به طور موقت تغییر کرده است. ممکن است در آینده تغییرات بیشتری در این نشانی ایجاد شود، بنابراین کلاینت باید در درخواست‌های بعدی از همین نشانی استفاده کند.
• 303 مشاهده منبع دیگر (See Other): سرور این پاسخ را برای هدایت کاربر به دریافت منبع درخواست شده از نشانی اینترنتی دیگری با استفاده از درخواست GET ارسال می‌کند.
• 304 تغییر نیافته ( Not Modified): این کد برای اهداف کشینگ (ذخیره‌سازی موقت) استفاده می‌شود. به کاربر اطلاع می‌دهد که پاسخ تغییر نکرده است، بنابراین کاربر می‌تواند همچنان از نسخه کش شده قبلی پاسخ استفاده کند.
• 307 تغییر مسیر موقت (Temporary Redirect): سرور این پاسخ را برای هدایت کلاینت به دریافت منبع درخواست شده از نشانی اینترنتی دیگری با همان روشی که در درخواست قبلی استفاده شده بود، ارسال می‌کند. این کد معنایی مشابه با کد پاسخ 302 یافت شد دارد، با این تفاوت که عامل کاربر نباید روش HTTP استفاده شده را تغییر دهد.
• 308 تغییر مسیر دائمی (Permanent Redirect): این بدان معناست که منبع اکنون به طور دائم در نشانی اینترنتی دیگری قرار دارد که در هدر پاسخ Location مشخص شده است. این کد معنایی مشابه با کد پاسخ HTTP 301 انتقال دائمی دارد، با این تفاوت که عامل کاربر نباید روش HTTP (متد و بدنه درخواست اصلی نیز در درخواست جدید حفظ شود) استفاده شده را تغییر دهد.

کد وضعیت http سری 4xx؛ پاسخ‌های خطای سمت کاربر

• 400 درخواست نامعتبر (Bad Request): سرور نمی‌تواند یا نمی‌خواهد درخواست را به دلیل وجود مشکلی که به نظر می‌رسد ناشی از خطای کاربر باشد (مانند اشتباه در ساختار درخواست، قالب‌بندی نامعتبر پیام درخواست، یا مسیریابی فریبنده درخواست) پردازش کند.
• 401 غیرمجاز (Unauthorized): اگرچه استاندارد HTTP عبارت “غیرمجاز” را مشخص کرده است، اما معنای ضمنی این پاسخ “تأیید هویت نشده” است. به این معنی که کاربر برای دریافت پاسخ مورد نظر باید ابتدا هویت خود را به سرور اثبات کند.
• 402 پرداخت مورد نیاز (Payment Required): هدف اولیه این کد برای سیستم‌های پرداخت دیجیتال بود، اما این وضعیت به ندرت استفاده می‌شود و هیچ توافق استاندارد برای آن وجود ندارد.
• 403 ممنوع (Forbidden): کاربر حق دسترسی به محتوا را ندارد؛ به عبارت دیگر، غیرمجاز است و سرور از ارائه منبع درخواستی خودداری می‌کند. برخلاف خطای 401 (غیرمجاز)، هویت کاربر برای سرور مشخص است.
• 404 یافت نشد (Not Found): منبع مورد نظر روی سرور پیدا نشد. در مرورگر، این به معنای عدم شناسایی آدرس اینترنتی (URL) است. در یک API، این می‌تواند به این معنی باشد که نقطه پایانی (endpoint) معتبر است اما خود منبع وجود ندارد.
• 405 روش غیرمجاز (Method Not Allowed): روش درخواست توسط سرور شناخته شده است اما توسط منبع مورد نظر پشتیبانی نمی‌شود.
• 406 غیرقابل قبول (Not Acceptable): این پاسخ زمانی ارسال می‌شود که سرور وب پس از انجام مذاکره محتوای مبتنی بر سرور، هیچ محتوایی مطابق با معیارهای ارائه شده توسط عامل کاربر پیدا نکند.
• 407 احراز هویت پراکسی مورد نیاز (Proxy Authentication Required): این خطا مشابه خطای 401 (غیرمجاز) است، اما احراز هویت باید توسط یک پراکسی انجام شود.
• 408 زمان درخواست به پایان رسیده (Request Timeout): این پاسخ توسط برخی سرورها در یک اتصال غیرفعال، حتی بدون هیچ درخواست قبلی از سوی کاربر، ارسال می‌شود. این بدان معناست که سرور می‌خواهد این اتصال بلااستفاده را قطع کند. این پاسخ از زمانی که برخی مرورگرها از مکانیسم‌های پیش‌اتصال HTTP برای تسریع مرور استفاده می‌کنند، بسیار بیشتر مورد استفاده قرار می‌گیرد.
• 409 تعارض (Conflict): این پاسخ زمانی ارسال می‌شود که یک درخواست با وضعیت فعلی سرور در تضاد باشد. به دلیل تعارض با وضعیت فعلی منبع، درخواست قابل انجام نیست.
• 410 حذف شده (Gone): این پاسخ زمانی ارسال می‌شود که محتوای درخواستی به طور دائم از سرور حذف شده باشد و هیچ آدرس ارجاعی وجود نداشته باشد.
• 411 طول مورد نیاز (Length Required): سرور درخواست را رد کرد زیرا فیلد هدر Content-Length تعریف نشده است و سرور به آن نیاز دارد.
• 412 پیش‌شرط ناموفق (Precondition Failed): در درخواست‌های شرطی، کاربر پیش‌شرط‌هایی را در هدرهای خود مشخص کرده است که سرور آن‌ها را برآورده نمی‌کند.
• 413 محتوا بسیار بزرگ است (Content Too Large): بدنه درخواست بزرگتر از محدودیت‌های تعیین شده توسط سرور است.
• 414 آدرس اینترنتی بسیار طولانی است (URI Too Long): آدرس اینترنتی درخواستی توسط کاربر طولانی‌تر از آن است که سرور مایل به تفسیر آن باشد.
• 415 نوع رسانه پشتیبانی نمی‌شود (Unsupported Media Type): فرمت رسانه‌ای داده‌های درخواستی توسط سرور پشتیبانی نمی‌شود.
• 416 محدوده غیرقابل قبول (Range Not Satisfiable): محدوده‌های مشخص شده توسط فیلد هدر Range در درخواست قابل اجرا نیستند.
• 417 انتظار ناموفق (Expectation Failed): این کد پاسخ به این معنی است که انتظاری که توسط فیلد هدر Expect در درخواست نشان داده شده است، توسط سرور قابل برآورده شدن نیست.
• 421 درخواست اشتباه هدایت شده (Misdirected Request): درخواست به سروری ارسال شده است که قادر به تولید پاسخ نیست. این می‌تواند توسط سروری ارسال شود که برای تولید پاسخ برای ترکیب طرح و مرجع موجود در URI درخواست پیکربندی نشده است.
• 422 محتوای غیرقابل پردازش (Unprocessable Content): درخواست به خوبی شکل گرفته بود اما به دلیل خطاهای معنایی قابل پیگیری نبود.
• 423 قفل شده (Locked): منبعی که در حال دسترسی است، قفل شده است.
• 424 وابستگی ناموفق (Failed Dependency): درخواست به دلیل عدم موفقیت یک درخواست قبلی با شکست مواجه شد.
• 426 ارتقاء مورد نیاز (Upgrade Required): سرور از انجام درخواست با استفاده از پروتکل فعلی خودداری می‌کند اما ممکن است پس از ارتقاء کاربر به پروتکل دیگری مایل به انجام آن باشد.
• 429 درخواست‌های بسیار زیاد (Too Many Requests): کاربر در یک بازه زمانی مشخص، درخواست‌های بسیار زیادی ارسال کرده است.
• 431 فیلدهای هدر درخواست بسیار بزرگ هستند (Request Header Fields Too Large): سرور تمایلی به پردازش درخواست ندارد زیرا فیلدهای هدر آن بسیار بزرگ هستند. پس از کاهش اندازه فیلدهای هدر درخواست، ممکن است درخواست دوباره ارسال شود.
• 451 غیرقابل دسترس به دلایل قانونی (Unavailable For Legal Reasons): عامل کاربر منبعی را درخواست کرده است که ارائه آن از نظر قانونی امکان‌پذیر نیست، مانند یک صفحه وب که توسط دولت سانسور شده است.

کد وضعیت http سری 5xx؛ پاسخ‌های خطای سرور

• 500 خطای داخلی سرور (Internal Server Error): سرور با وضعیتی مواجه شده است که نمی‌داند چگونه آن را مدیریت کند. این یک خطای کلی است و نشان می‌دهد که سرور نمی‌تواند کد وضعیت 5XX مناسب‌تری برای پاسخ دادن پیدا کند.
• 501 پیاده‌سازی نشده (Not Implemented): روش درخواست توسط سرور پشتیبانی نمی‌شود و قابل رسیدگی نیست.
• 502 درگاه نامعتبر (Bad Gateway): این پاسخ خطا به این معنی است که سرور، در حین کار به عنوان یک درگاه برای دریافت پاسخی که برای رسیدگی به درخواست لازم است، یک پاسخ نامعتبر دریافت کرده است.
• 503 سرویس در دسترس نیست (Service Unavailable): سرور برای رسیدگی به درخواست آماده نیست. علل رایج آن می‌تواند از کار افتادن سرور برای تعمیر و نگهداری یا بارگذاری بیش از حد آن باشد.
• 504 زمان انتظار درگاه به پایان رسید (Gateway Timeout): این پاسخ خطا زمانی داده می‌شود که سرور به عنوان یک درگاه عمل می‌کند و نمی‌تواند در زمان مقرر پاسخی دریافت کند.
• 505 نسخه HTTP پشتیبانی نمی‌شود (HTTP Version Not Supported): نسخه HTTP استفاده شده در درخواست توسط سرور پشتیبانی نمی‌شود.
• 506 نوع متغیر نیز مذاکره می‌کند (Variant Also Negotiates): سرور با یک خطای پیکربندی داخلی مواجه شده است: در طول مذاکره محتوا، نوع متغیر انتخاب شده به گونه‌ای پیکربندی شده است که خود در مذاکره محتوا شرکت کند، که منجر به ارجاعات حلقوی در هنگام ایجاد پاسخ‌ها می‌شود.
• 507 فضای ذخیره‌سازی ناکافی (Insufficient Storage): این روش روی منبع قابل اجرا نیست زیرا سرور قادر به ذخیره نمایشی که برای تکمیل موفقیت‌آمیز درخواست لازم است، نیست.
• 508 حلقه شناسایی شد ( Loop Detected): سرور هنگام پردازش درخواست، یک حلقه بی‌نهایت را شناسایی کرد.
• 510 توسعه نیافته (Not Extended): برای پردازش این درخواست، نیاز به افزونه‌ها یا اطلاعات تکمیلی بیشتری وجود دارد.
• 511 احراز هویت شبکه مورد نیاز است (Network Authentication Required): نشان می‌دهد که مشتری برای دسترسی به شبکه نیاز به احراز هویت دارد.

نکات عملی برای مدیریت کدهای وضعیت HTTP

• طراحی API: هنگام طراحی API، از کدهای وضعیت مناسب استفاده کنید تا کلاینت‌ها بتوانند به‌راحتی خطاها را مدیریت کنند.
• پیام‌های خطا: پیام‌های خطای واضح و کاربرپسند ارائه دهید، به‌ویژه برای کدهای 4xx و 5xx.
• لاگ‌گیری: لاگ‌های سرور را برای شناسایی مشکلات مرتبط با کدهای 5xx بررسی کنید.
• تست و اعتبارسنجی: درخواست‌ها و پاسخ‌ها را در محیط توسعه تست کنید تا از استفاده صحیح کدها اطمینان حاصل شود.
• مدیریت کش: برای کدهای 3xx و 304، تنظیمات کش را به‌دقت مدیریت کنید.

نتیجه‌گیری

کدهای وضعیت HTTP بخش حیاتی از پروتکل HTTP هستند که ارتباط بین کلاینت و سرور را تسهیل می‌کنند. درک دقیق این کدها، کاربردها و مشکلات مرتبط با آن‌ها به توسعه‌دهندگان کمک می‌کند تا برنامه‌های وب پایدارتر و کاربرپسندتری طراحی کنند. با رعایت نکات عملی و مدیریت صحیح خطاها، می‌توان تجربه کاربری بهتری ارائه داد و از مشکلات رایج جلوگیری کرد.