راهنمای جامع خطاهای رایج در توسعه وب؛ از خطاهای HTTP تا خطاهای Backend و Frontend

وقتی کاربر می‌گوید «سایت کار نمی‌کند»، معمولاً یک عدد سه‌رقمی، یک پیام قرمز در Console، یا یک لاگ Backend پشت صحنه است. تفاوت تیم‌های سریع با تیم‌های گیج‌شده این نیست که خطا نمی‌بینند؛ این است که سریع می‌فهمند خطا مال کلاینت است، مال قرارداد API است، مال داده است، یا مال استقرار.

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

این مقاله یک مرجع عملیاتی است: برای هر کد رایج، معنی، علت‌های پرتکرار، روش تشخیص، راه‌حل، و معیار «چه زمانی متخصص باید وارد شود». سپس خطاهای JavaScript، API، پایگاه داده (Database) و استقرار (Deployment) را جدا می‌کند تا مسیر اقدام روشن باشد.

مخاطب فقط توسعه‌دهنده نیست؛ مدیر محصول و صاحب کسب‌وکار هم باید بدانند کدام خطا موقتی است و چه زمانی Retry خطرناک است.

پاسخ کوتاه

خطاهای رایج توسعه وب را اول با کلاس کد جدا کنید: ۴xx یعنی درخواست با این شکل قابل‌اجرا نیست؛ ۵xx یعنی سرویس یا مسیر پشت آن شکست خورده است. سپس لایه را پیدا کنید: Frontend، Backend، Database، یا Deployment.

تشخیص خوب سه چیز می‌خواهد: کد وضعیت و بدنهٔ پاسخ، لاگ هم‌زمان با شناسهٔ درخواست (Request ID)، و بازتولید با همان هویت و همان روش HTTP. راه‌حل بدون این سه مورد اغلب حدس است.

کد وضعیت را مثل چراغ راهنما بخوانید، نه مثل حکم دادگاه. علت در لاگ، در قرارداد API، و در لایهٔ صادرکننده است.

• ۴xx را بدون تغییر ورودی/هویت/زمان تکرار نکنید؛ به‌جز ۴۰۸ و ۴۲۹ با backoff.
• ۵۰۳ و بعضی ۵۰۲/۵۰۴ موقتی را می‌توان با فاصله تکرار کرد؛ پرداخت و ثبت سفارش را کور تکرار نکنید.
• پیام CORS در Console اغلب یعنی مرورگر پاسخ را از اسکریپت پنهان کرده؛ Postman این لایه را ندارد.
• اگر خطا روی مسیر پول‌ساز بیش از چند دقیقه پایدار است، یا علت بین لایه‌ها مبهم مانده، متخصص همان لایه را صدا کنید.

جدول مقایسهٔ کلاس‌های HTTP

قبل از عدد دقیق، کلاس را بشناسید. MDN و RFC 9110 کدها را در پنج کلاس گروه‌بندی می‌کنند.

از نگاه SEO، طبق مستند Google Search Central، کدهای ۴xx به‌جز ۴۲۹ معمولاً محتوا را از پردازش خارج می‌کنند؛ ۴۲۹ و ۵xx مثل اضافه‌بار سرور دیده می‌شوند و crawl را موقتاً کند می‌کنند.

خطاهای ۴xx؛ تشخیص و رفع عملیاتی

کلاس ۴xx یعنی سرور درخواست را فهمیده یا حداقل دریافت کرده و آن را اجرا نمی‌کند. مسئولیت اول معمولاً با شکل درخواست، هویت، یا قرارداد است — نه با «خاموش بودن سرور».

400 Bad Request

معنی: سرور به‌خاطر خطای کلاینت درخواست را پردازش نمی‌کند؛ نحو خراب، framing نامعتبر، یا مسیریابی فریبنده.

علت‌های رایج: JSON ناقص، Content-Type اشتباه، فیلد اجباری خالی در لایهٔ parse، یا پروکسی که هدر را خراب می‌کند.

روش تشخیص: در DevTools بدنه و هدر خام را ببینید؛ همان درخواست را با curl بازسازی کنید؛ در لاگ Backend خط parse را با Request ID پیدا کنید.

راه‌حل: قرارداد ورودی را در کلاینت و سرور هم‌تراز کنید؛ پیام خطا باید فیلد معیوب را بگوید، نه فقط Bad Request.

چه زمانی متخصص: اگر فقط روی یک مسیر خاص یا پشت CDN رخ می‌دهد و بدنهٔ خام سالم به‌نظر می‌رسد — احتمال دستکاری intermediary است و نیاز به مهندس شبکه/پلتفرم دارد.

401 Unauthorized

معنی: از نظر معنایی «احراز هویت نشده» است، هرچند نام انگلیسی گمراه‌کننده است. کلاینت باید خودش را معرفی کند.

علت‌های رایج: توکن منقضی، کوکی نشست حذف‌شده، هدر Authorization جاافتاده، اختلاف ساعت در JWT.

روش تشخیص: آیا WWW-Authenticate یا بدنهٔ استاندارد auth برگشته؟ آیا همان درخواست با توکن تازه ۲۰۰ می‌شود؟

راه‌حل: جریان تمدید توکن (refresh) را اصلاح کنید؛ کاربر را به ورود هدایت کنید؛ ساعت سرورها را با NTP هم‌زمان نگه دارید.

چه زمانی متخصص: نشتی توکن، شکست سراسری SSO، یا ۴۰۱ ناگهانی روی همهٔ سرویس‌ها — امنیت/هویت را درگیر کنید.

403 Forbidden

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

علت‌های رایج: نقش ناکافی، ACL اشتباه، WAF، محدودیت IP، یا قوانین کسب‌وکار روی منبع.

روش تشخیص: با دو حساب متفاوت مقایسه کنید؛ سیاست IAM و قوانین WAF را هم‌زمان ببینید؛ ۴۰۳ را با ۴۰۱ و ۴۰۴ اشتباه نگیرید.

راه‌حل: مجوز را در منبع درست کنید؛ اگر پنهان‌کردن وجود منبع هدف است، طبق RFC 9110 گاهی ۴۰۴ عمدی مناسب‌تر است.

چه زمانی متخصص: قفل شدن نقش‌های حیاتی، یا ۴۰۳ ناشی از WAF/فایروال که تیم اپ نمی‌تواند ببیند.

404 Not Found

معنی: representation پیدا نشد، یا سرور نمی‌خواهد وجود منبع را فاش کند.

علت‌های رایج: URL غلط، مسیر Frontend/Backend ناهماهنگ، رکورد حذف‌شده، rewrite اشتباه بعد از deploy.

روش تشخیص: مسیر را در اپ و در gateway مقایسه کنید؛ آیا منبع در دیتابیس هست؟ آیا CDN مسیر قدیمی را می‌زند؟

راه‌حل: مسیر را درست کنید؛ برای URL مهم حذف‌شده از ۳۰۱ به جایگزین استفاده کنید؛ صفحهٔ ۴۰۴ انسانی با مسیر بازگشت بسازید.

چه زمانی متخصص: موج ۴۰۴ بعد از انتشار روی URLهای پول‌ساز یا ایندکس‌شده — اولویت SEO/پلتفرم.

405 Method Not Allowed

معنی: روش HTTP برای آن منبع مجاز نیست. پاسخ باید Allow داشته باشد.

علت‌های رایج: POST به‌جای PUT، DELETE روی منبع فقط‌خواندنی، یا فرم HTML که روش را اشتباه می‌فرستد.

روش تشخیص: روش واقعی را در Network ببینید؛ Allow را بخوانید؛ مستند قرارداد API را با پیاده‌سازی مقایسه کنید.

راه‌حل: روش را با قرارداد هم‌تراز کنید؛ در مستند OpenAPI روش‌های مجاز را صریح بنویسید.

چه زمانی متخصص: اگر gateway روش را قبل از اپ می‌بلعد و تیم اپ Allow را کنترل نمی‌کند.

408 Request Timeout

معنی: سرور در فرصت معقول درخواست کامل را نگرفته است. با ۵۰۴ فرق دارد: این‌جا خود درخواست تمام نشده.

علت‌های رایج: آپلود کند، اتصال ناپایدار کاربر، timeout کوتاه سمت سرور روی بدنهٔ بزرگ.

روش تشخیص: اندازهٔ بدنه و زمان تا اولین بایت را ببینید؛ آیا کلاینت هنوز در حال ارسال است؟

راه‌حل: آپلود تکه‌ای، فشرده‌سازی، افزایش منطقی timeout فقط برای مسیرهای مشخص، و پیام واضح به کاربر.

چه زمانی متخصص: اگر فقط از یک منطقه یا ISP رخ می‌دهد — شبکه/CDN.

409 Conflict

معنی: درخواست با وضعیت فعلی منبع تعارض دارد.

علت‌های رایج: ویرایش همزمان، موجودی تکراری، شکست ETag/If-Match، قید یکتای پایگاه داده که درست به ۴۰۹ نگاشت شده.

روش تشخیص: آیا دو نویسنده روی یک رکورد بوده‌اند؟ آیا version/ETag ارسال شده؟

راه‌حل: قفل خوش‌بینانه، پیام تعارض قابل‌فهم، و جلوگیری از تبدیل خام constraint به ۵۰۰.

چه زمانی متخصص: تعارض‌های گسترده در دادهٔ مالی یا موجودی که به یکپارچگی دامنه برمی‌گردد.

422 Unprocessable Content

معنی: نحو درست است و نوع محتوا فهمیده شده، اما معنای محتوا قابل‌اجرا نیست. RFC 9110 نام را Unprocessable Content می‌گذارد.

علت‌های رایج: اعتبارسنجی دامنه (تاریخ پایان قبل از شروع)، وابستگی فیلدها، قوانین کسب‌وکار.

روش تشخیص: اگر parse موفق است ولی validator رد می‌کند، ۴۲۲ درست‌تر از ۴۰۰ است.

راه‌حل: خطاهای فیلد‌به‌فیلد برگردانید؛ در UI همان فیلد را علامت بزنید.

چه زمانی متخصص: وقتی قوانین اعتبارسنجی بین چند سرویس متناقض شده و نیاز به مالک دامنه دارد.

429 Too Many Requests

معنی: کاربر در بازهٔ زمانی بیش از حد درخواست فرستاده (Rate Limiting). RFC 6585 می‌گوید توضیح بدهید و می‌توانید Retry-After بفرستید؛ این پاسخ نباید cache شود.

علت‌های رایج: حلقهٔ Frontend، اسکریپت، سقف API، یا اشتراک IP پشت NAT.

روش تشخیص: هدر Retry-After و شناسهٔ محدودیت را ببینید؛ آیا یک کلاینت خاص است یا همه؟

راه‌حل: backoff نمایی، صف‌کردن، کاهش polling؛ سقف را با واقعیت محصول تنظیم کنید.

چه زمانی متخصص: اگر Googlebot یا خزندهٔ مهم ۴۲۹ می‌گیرد — طبق Google این کد مثل خطای سرور رفتار می‌شود و crawl را کند می‌کند؛ کنترل crawl با ۴۲۹ روش درستی نیست.

خطاهای ۵xx؛ وقتی سرویس یا مسیر پشت آن می‌شکند

۵xx یعنی مشکل از سمت سرویس است. کاربر کارش تمام نمی‌شود؛ تیم باید لایه را جدا کند: exception برنامه، upstream، ظرفیت، یا مهلت زمانی.

500 Internal Server Error

معنی: سرور با وضعیتی روبه‌رو شده که پاسخ دقیق‌تری برایش ندارد؛ برنامه غافلگیر شده است.

علت‌های رایج: exception مدیریت‌نشده، فرض غلط روی داده، وابستگی null، باگ بعد از deploy.

روش تشخیص: stack trace در لاگ داخلی (نه صفحهٔ عمومی)، correlation با نسخهٔ انتشار، نرخ خطا روی endpoint.

راه‌حل: رفع ریشه، صفحهٔ خطا با شناسهٔ حادثه، جلوگیری از نشت جزئیات به کاربر.

چه زمانی متخصص: جهش ناگهانی ۵۰۰ روی چند سرویس، یا خطای مرتبط با امنیت/دادهٔ حساس.

502 Bad Gateway

معنی: میانجی زنده است اما از upstream پاسخ نامعتبر گرفته است.

علت‌های رایج: process کرش، origin هنوز listen نمی‌کند، پاسخ ناقص، قطع ارتباط بین proxy و اپ.

روش تشخیص: آیا origin سالم است؟ healthcheck چه می‌گوید؟ آیا فقط از پشت gateway است؟

راه‌حل: پایدار کردن process، اصلاح upstream، بررسی timeout و buffer پروکسی.

چه زمانی متخصص: وقتی اپ محلی سالم است ولی فقط از لبه/لودبالانسر ۵۰۲ می‌آید.

503 Service Unavailable

معنی: سرویس موقتاً آماده نیست؛ نگهداری یا اضافه‌بار. بهتر است انسانی باشد و در صورت امکان Retry-After داشته باشد؛ معمولاً نباید روی CDN بماند.

علت‌های رایج: deploy با قطعی، اشباع worker، قطع وابستگی حیاتی، حالت maintenance.

روش تشخیص: متریک ظرفیت، صف درخواست، وضعیت maintenance flag.

راه‌حل: مقیاس‌دهی، قطع ویژگی غیرحیاتی، صفحهٔ تعمیرات واقعی با ۵۰۳ نه ۲۰۰.

چه زمانی متخصص: اگر ظرفیت یا معماری صف پاسخگوی بار واقعی نیست.

504 Gateway Timeout

معنی: میانجی منتظر upstream ماند و زمان تمام شد؛ پاسخ خراب نیامده، دیر آمده.

علت‌های رایج: کوئری سنگین Database، سرویس ثالث کند، timeout کوتاه‌تر از کار واقعی.

روش تشخیص: زمان‌سنجی هر hop؛ آیا DB یا پرداخت bottleneck است؟

راه‌حل: بهینه‌سازی کوئری، کار ناهمگام، تنظیم آگاهانهٔ timeout، مدارشکن (circuit breaker).

چه زمانی متخصص: ۵۰۴های مزمن روی مسیر پرداخت/گزارش که نیاز به DBA یا معماری دارد.

خطاهای JavaScript در مرورگر

خیلی از «دکمه کار نمی‌کند»ها اصلاً کد HTTP نیستند. در Console مرورگر، TypeError و ReferenceError از خانوادهٔ Error در JavaScriptاند.

TypeError

وقتی نوع مقدار غیرمنتظره است؛ اغلب null/undefined. پیام معروف: خواندن property از undefined. اول دادهٔ API را guard کنید؛ بعد UI را رندر کنید.

ReferenceError

متغیر در scope موجود نیست؛ یا کتابخانه قبل از استفاده لود نشده. ترتیب اسکریپت و import را بررسی کنید.

Uncaught و Promise

Uncaught یعنی exception بدون catch به سطح بالا رسیده. در async، rejection بدون handler همان حس را می‌دهد. دست‌کم یک مرز خطا در UI و یک گزارش به سامانهٔ مشاهده‌پذیری بگذارید.

CORS در Console

اشتراک منابع بین مبدأها (CORS) را مرورگر اعمال می‌کند. شکست CORS جزئیات را از JavaScript پنهان می‌کند؛ فقط Console توضیح می‌دهد. موفقیت در Postman اثبات مجوز مرورگر نیست. هدرهای Access-Control-* را در origin درست تنظیم کنید.

خطاهای API؛ قرارداد، زمان و تکرارپذیری

خطای API فقط status نیست؛ نقض قرارداد (contract) است: فیلد عوض‌شده، نوع داده، یا معنای کد.

• ۴xx یعنی کلاینت باید رفتارش را عوض کند؛ ۵xx یعنی سرویس را درمان کنید.
• Timeout سمت کلاینت را با ۴۰۸/۵۰۴ سرور یکی فرض نکنید؛ هر کدام لایهٔ خودش را دارد.
• Idempotency: GET معمولاً امن برای Retry است؛ POST پرداخت بدون کلیدidempotency خطر دوباره‌کاری دارد.
• بدنهٔ خطا را استاندارد کنید: کد ماشین‌خوان، پیام انسان‌خوان، Request ID.

اگر نسخهٔ API و کلاینت از هم دور شده‌اند، موج ۴۰۰/۴۲۲ بعد از انتشار طبیعی است؛ اول قرارداد را قفل کنید.

خطاهای Database؛ مفهومی و قابل‌اقدام

این‌جا آمار فروشنده نمی‌آوریم؛ الگوهای مشترک را می‌گوییم.

• Connection: تمام شدن pool، اشتباه بودن host/credential، محدودیت اتصال — معمولاً به ۵۰۲/۵۰۳/۵۰۰ می‌انجامد.
• Timeout: کوئری طولانی یا قفل؛ اغلب ریشهٔ ۵۰۴.
• Constraint: یکتا بودن، کلید خارجی — بهتر است به ۴۰۹ یا ۴۲۲ نگاشت شود، نه ۵۰۰ خام.
• Deadlock: دو تراکنش منتظر هم؛ Retry کنترل‌شده روی تراکنش کوتاه گاهی درست است.

exception دیتابیس را در پاسخ عمومی نگذارید. برای مدیر محصول: کندی گزارش‌ها را با «سایت خواب است» یکی نکنید؛ مسیر را جدا پایش کنید.

خطاهای Deployment

بسیاری از ۵xxها باگ منطق نیستند؛ ناهماهنگی انتشارند.

• Env mismatch: متغیر محیط Staging روی Production، کلید پرداخت تست، URL سرویس غلط.
• Migration:스키ما جلوتر یا عقب‌تر از کد؛ خواندن ستونی که هنوز نیست.
• Healthcheck: لبه ترافیک می‌فرستد ولی ready نیست → ۵۰۲.
• Rolling fail: بخشی از instanceها نسخهٔ بد دارند؛ خطا متناوب و گمراه‌کننده می‌شود.

چک‌لیست حداقلی قبل از اعلام «تمام»: health سبز، migration موفق، یک smoke روی مسیر پول‌ساز، و آمادگی rollback.

چه زمانی خودتان کافی‌اید و چه زمانی متخصص؟

قاعدهٔ ساده: اگر مسیر پرداخت، ورود، یا ثبت سفارش بیش از چند دقیقه خراب است و علت در یک لایه قفل نشده، Escalation را عقب نندازید.

جمع‌بندی

خطاهای رایج توسعه وب وقتی گران می‌شوند که عدد را ببینید و لایه را نبینید. ۴xx را با اصلاح درخواست درمان کنید؛ ۵xx را با پایدار کردن سرویس و مسیر.

برای تیم فنی: هر کد را با تشخیص و معیار Specialist در runbook بگذارید. برای مدیر: «صفر خطا» نخواهید؛ بخواهید خطاهای پول‌ساز سریع طبقه و مالک پیدا کنند.

اگر برای طراحی صفحهٔ خطا، قرارداد API، یا مشاهده‌پذیری مطمئن نیستید، اول سه مسیر حیاتی محصول را مشخص کنید و همان‌ها را با Request ID واقعی تمرین عیب‌یابی کنید.

منابع و مراجع

• RFC 9110 — HTTP Semantics (IETF): https://www.rfc-editor.org/rfc/rfc9110
• RFC 6585 — Additional HTTP Status Codes؛ بخش 429 (IETF): https://www.rfc-editor.org/rfc/rfc6585
• MDN — HTTP response status codes: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status
• MDN — Error: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error
• MDN — TypeError: "x" is (not) "y": https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Errors/Unexpected_type
• MDN — ReferenceError: "x" is not defined: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Errors/Not_defined
• MDN — Cross-Origin Resource Sharing (CORS): https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS
• Google Search Central — How HTTP status codes affect Google's crawlers (به‌روزرسانی ۴ فوریه ۲۰۲۶): https://developers.google.com/search/docs/crawling-indexing/http-network-errors