API فقط با status code قابلدیباگ نیست؛ قرارداد خطای قابلخواندن بساز
frontend فقط «500» میبیند یا برای تشخیص خطا مجبور است متن پیام backend را مقایسه کند.
برای خطاهای قابل انتظار، code ثابت، پیام قابلفهم و جزئیات امن برگردان تا client مجبور به parse کردن متن آزاد نشود.
چطور دقیقتر به موضوع نگاه کنیم؟
- برای خطاهای کسبوکار code پایدار تعریف کن؛ مثل EMAIL_EXISTS یا LIMIT_REACHED.
- HTTP status را با نوع نتیجه هماهنگ کن و همه خطاها را 200 برنگردان.
- پیام کاربر و جزئیات داخلی را جدا نگه دار تا stack یا secret لو نرود.
- request id را برای پیگیری خطا بین client و logها اضافه کن.
چرا این موضوع مهم است؟
متن آزاد تغییر میکند و برای منطق برنامه مناسب نیست. error contract ثابت ارتباط سرویسها و observability را بهتر میکند.
سؤالهایی که معمولاً بعدش پیش میآید
پیام خطا را فارسی برگردانیم؟
منطق client بهتر است روی code ثابت باشد؛ متن میتواند در لایه نمایش محلیسازی شود.
همه validationها 400 هستند؟
جزئیات طراحی API فرق میکند؛ قرارداد باید مستند و ثابت باشد.