خطاهای API

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

فرمت خطا

در صورت خطا، بدنه پاسخ یک شیء JSON با یک فیلد error است که پیام قابل‌خواندن برای انسان را شامل می‌شود:

{"error":"reaction not found"}

ابتدا بر کد وضعیت HTTP تکیه کنید و متن error را برای لاگ‌ها و راهنمایی کاربر استفاده کنید.

کدهای وضعیت

  • 200 OK — درخواست موفق، داده‌ها در بدنه.
  • 201 Created — منبع جدید ایجاد شد (برخی اندپوینت‌های POST).
  • 204 No Content — موفق بدون بدنه (برخی حذف‌ها).
  • 400 Bad Request — بدنه یا پارامترهای درخواست نادرست.
  • 401 Unauthorized — توکن وجود ندارد، نادرست یا منقضی شده؛ یا مسیر با توکن شخصی در دسترس نیست.
  • 402 Payment Required — عملیات به طرح یا سهمیه برخورده (مثلاً ذخیره‌سازی رسانه شخصی نیاز به premium دارد).
  • 403 Forbidden — توکن فاقد حوزه لازم برای این مسیر است.
  • 404 Not Found — منبع یافت نشد یا متعلق به شما نیست.
  • 409 Conflict — تعارض وضعیت (مثلاً تکراری بودن مقدار یکتا).
  • 422 Unprocessable Entity — بدنه از نظر نحوی معتبر است اما بررسی‌های دامنه را رد می‌کند.
  • 429 Too Many Requests — محدودیت درخواست تجاوز شده (ببینید محدودیت‌ها).
  • 500 Internal Server Error — خطای داخلی سرور؛ بعداً دوباره امتحان کنید.

نحوه پردازش

کدهای 2xx را موفق بدانید. برای 401/403 توکن و حوزه‌های آن را بررسی کنید. برای 4xx (به‌جز 429) بدون تغییر درخواست را تکرار نکنید — درخواست را اصلاح کنید. برای 429 و 5xx تکرار با تأخیر نمایی مناسب است.

بیشتر بخوانید