مرجع خطاها

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

شکل بدنهٔ خطا

بدنهٔ خطا همیشه یک فیلد detail دارد و فیلد ok ندارد:

{"detail": "missing scope targets:write"}

بر اساس کد وضعیت HTTP تصمیم بگیرید، نه متن بدنه. متن detail برای انسان است و ممکن است تغییر کند؛ الگوی ثابت، وضعیت HTTP است.

جدول مرجع

چهار موردی که بیشتر غافلگیر می‌کنند

404 برای شناسهٔ دیگران

task_id یا target_id یک حساب دیگر 404 می‌گیرد، نه 403. وجودش فاش نمی‌شود؛ 403 تأیید می‌کرد که این شناسه واقعی است.

404 برای درخواستی که چیزی را عوض نکرد

PATCH /targets/{id} وقتی واقعاً هیچ فیلدی تغییر نکرده باشد 404 می‌گیرد. این عمدی است تا این پرسش قابل پاسخ بماند که «ویرایش من اعمال شد؟».

422 برای فیلد ناشناخته

فیلد ناشناختهٔ بدنه رد می‌شود، نه اینکه بی‌صدا دور ریخته شود. یک املای غلط مثل cadence_hour در غیر این صورت نادیده گرفته می‌شد و زمان‌بندی شما هرگز تغییر نمی‌کرد.

422 برای فیلد غیرقابل تغییر

آن سه‌تایی هویت هدف است و تغییر نمی‌کند. کلمهٔ کلیدیِ ذخیره‌شده همان چیزی است که واقعاً جستجو می‌شود؛ تغییرش تاریخچه را بازنویسی می‌کند، نه اینکه آن را ویرایش. برای رهگیری یک پرس‌وجوی متفاوت، DELETE کنید و بعد POST — در اهداف توضیح داده شده.

کدام خطا را تلاش مجدد کنیم

این جدول تصمیم است، نه جدول مرجع:

حالتی که در جدول نیست: Blocked

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

الگوی کلی

if r.status_code in (401, 403):
    raise ConfigurationError("کلید یا مجوز را اصلاح کنید")   # تلاش مجدد بی‌فایده
if r.status_code == 404:
    raise LookupError("پیدا نشد، یا متعلق به شما نیست")
if r.status_code == 422:
    raise ValueError(r.json()["detail"])                        # بدنهٔ ورودی غلط
if r.status_code == 429:
    time.sleep(int(r.headers["Retry-After"]))                   # تنها موردی که صبر می‌کند
r.raise_for_status()