خطاها

شکل پاسخ خطا

هر خطا با بدنه‌ای به قالب JSON، مثل این، پاسخ داده می‌شود:

{
  "error": {
    "code": "TOKEN_DAILY_CAP",
    "message": "This token's daily minute cap is reached",
    "details": { "capMinutes": 60, "usedMinutes": 55, "requiredMinutes": 12 }
  }
}

• code قرارداد است. منطق برنامه‌تان را بر اساس آن بنویسید.

• message توضیحی برای خواندن است. آن را در لاگ بنویسید یا نشان دهید، اما هرگز برنامه را بر اساس آن ننویسید: ممکن است تغییر کند. پاسخ 500 برای خطای پیش‌بینی‌نشده، یعنی INTERNAL_ERROR، فقط code دارد.

• details فقط همراه چند کد می‌آید و عددهایی دارد که می‌توانید بر اساسشان کاری بکنید:

  کد	details
  402 INSUFFICIENT_MINUTES	requiredMinutes، و balanceMinutes برای توکنی با دسترسی account:read
  429 TOKEN_DAILY_CAP	capMinutes، usedMinutes و requiredMinutes
  409 PRICE_ABOVE_MAX	minutes و maxMinutes
  409 NOT_READY (جلسهٔ کامل)	status، کنار error و نه درون آن

• وضعیت HTTP به‌تنهایی کافی نیست. چند کد یک وضعیت مشترک دارند: بسیاری از پاسخ‌های متفاوت با 409 می‌آیند.

• مسیری زیر /api/ که جزو مسیرهای API نیست پاسخ متنی ساده‌ای با 404 Not Found می‌گیرد، نه این JSON را. مسیر را با مرجع API مقایسه کنید.

دو استثنا، همان‌طور که هستند

پاسخ 409 NOT_READY جلسهٔ کامل

GET /recordings/{id}/bundle برای جلسه‌ای که هنوز READY نیست، details را کنار error می‌گذارد، نه درون آن:

{
  "error": { "code": "NOT_READY", "message": "The meeting is not ready yet" },
  "details": { "status": "TRANSCRIBING" }
}

این پاسخ از خود این قاعده قدیمی‌تر است و جابه‌جا کردن details اسکریپت‌هایی را که آن را می‌خوانند از کار می‌اندازد، پس همین‌طور می‌ماند: این‌جا details.status را از بالاترین سطح بدنه بخوانید. این مقدار می‌گوید جلسه در چه مرحله‌ای است: منتظر READY بمانید، مگر این‌که FAILED باشد؛ در آن صورت FAILED و تلاش دوباره را ببینید.

402 INSUFFICIENT_MINUTES

details.requiredMinutes همیشه هست. details.balanceMinutes فقط برای توکنی می‌آید که دسترسی account:read دارد: توکنی که این دسترسی را ندارد هرگز موجودی را نمی‌بیند. این‌که این موجودی چه چیزی را حساب می‌کند در دقیقه‌ها، سقف‌ها و محدودیت‌ها آمده است.

کدهایی که شبیه هم‌اند

TOKEN_SCOPE و SCOPE_DISABLED

هر دو 403 هستند.

• TOKEN_SCOPE: توکن هیچ‌کدام از دسترسی‌هایی را که این مسیر لازم دارد ندارد، و هرگز هم نخواهد داشت، چون دسترسی‌های توکن هنگام ساختنش ثابت می‌شوند. دوباره نفرستید: صاحب حساب باید توکنی با آن دسترسی بسازد.
• SCOPE_DISABLED: توکن این دسترسی را دارد، اما لُب فعلاً این نوع دسترسی را خاموش کرده است. توکن سالم است: بعداً دوباره امتحان کنید.

توکنی که دسترسی لازم را ندارد همیشه TOKEN_SCOPE می‌گیرد، چه آن دسترسی خاموش باشد چه روشن. پس SCOPE_DISABLED همیشه یعنی توکن هر چه لازم است دارد و فقط باید صبر کند.

یادداشت

ارسال جلسه، ساختن و ویرایش سری، تغییر تنظیمات، جست‌وجو و پرسش با توکن به‌تدریج روشن می‌شوند. اگر فرم «اتصال‌ها» دسترسی‌ای را پیشنهاد نمی‌دهد، آن دسترسی هنوز برای حساب شما فعال نشده است.

TOKEN_INVALID و DEVELOPER_MODE_OFF

• TOKEN_INVALID (401): خود توکن مشکل دارد. ناشناخته، باطل‌شده یا منقضی است؛ هر سه یک کد دارند و پاسخ هرگز نمی‌گوید کدام. دوباره نفرستید: صاحب حساب باید در «اتصال‌ها» توکن تازه‌ای بسازد.
• DEVELOPER_MODE_OFF (403): توکن سالم است، اما صاحب حساب «حالت توسعه‌دهنده» را خاموش کرده و این کار همهٔ توکن‌های حساب را متوقف می‌کند. چیزی باطل نشده است: وقتی دوباره روشن شود، همان توکن باز کار می‌کند. این را نشانهٔ توکن نادرست ندانید و پشت سر هم تکرارش نکنید. از صاحب حساب بخواهید «حالت توسعه‌دهنده» را دوباره روشن کند: در برنامه، «حساب»، بخش «توسعه‌دهندگان».

توکن باطل‌شده یا منقضی در هر حال TOKEN_INVALID می‌گیرد: لُب پیش از «حالت توسعه‌دهنده» خود توکن را بررسی می‌کند.

همهٔ کدها

جدول زیر هر کد، وضعیت HTTP آن، معنایش و گام بعد را نشان می‌دهد. جدول با بررسی‌هایی شروع می‌شود که هر درخواست توکن از آن‌ها می‌گذرد، به همان ترتیبی که لُب انجامشان می‌دهد.

ستون آخر می‌گوید ابزار شما پس از آن چه کند:

• تکرار نکنید: همین درخواست بعداً هم خودبه‌خود درست نمی‌شود. اول باید چیزی تغییر کند، که اغلب کار صاحب حساب است.
• منتظر Retry-After بمانید: به اندازهٔ ثانیه‌هایی که می‌گوید صبر کنید و همان درخواست را دوباره بفرستید.
• درخواست را اصلاح کنید: خود درخواست نادرست است و message معمولاً می‌گوید چرا.
• بعداً دوباره امتحان کنید: درخواست درست است، اما فعلاً چیزی در سمت لُب، یا خاموش بودن یک قابلیت، مانع است.

وقتی درخواستی را دوباره می‌فرستید، همان Idempotency-Key را بفرستید؛ تکرارپذیری و تلاش دوباره را ببینید.

کد	وضعیت HTTP	معنا	گام بعد
UNAUTHORIZED	401	توکنی همراه درخواست نیامد (اگر هدر Authorization نباشد یا Bearer lobbe_… نباشد، درخواست مثل درخواستِ کسی خوانده می‌شود که وارد نشده است): هدر Authorization: Bearer lobbe_… را بفرستید.	درخواست را اصلاح کنید
TOKEN_NOT_ACCEPTED	401	این مسیر توکن API نمی‌پذیرد: فقط مسیرهایی را فراخوانی کنید که در مرجع API آمده‌اند.	درخواست را اصلاح کنید
TOKENS_DISABLED	401	لُب فعلاً توکن‌های API را برای همه خاموش کرده است و توکن شما سر جایش می‌ماند: بعداً دوباره امتحان کنید.	بعداً دوباره امتحان کنید
TOKEN_INVALID	401	توکن ناشناخته، باطل‌شده یا منقضی است و پاسخ نمی‌گوید کدام: دوباره نفرستید؛ صاحب حساب باید در «اتصال‌ها» توکن تازه‌ای بسازد.	تکرار نکنید
DEVELOPER_MODE_OFF	403	توکن سالم است، اما صاحب حساب «حالت توسعه‌دهنده» را در تنظیمات برنامه (بخش «توسعه‌دهندگان») خاموش کرده و تا وقتی دوباره روشنش کند همهٔ توکن‌های حساب متوقف‌اند: این را نشانهٔ توکن نادرست یا باطل‌شده ندانید و پشت سر هم تکرارش نکنید؛ از او بخواهید «حالت توسعه‌دهنده» را روشن کند.	تکرار نکنید
RATE_LIMITED	429	در زمان کوتاهی درخواست‌های زیادی رسید، از این توکن یا از نشانی IP شما: به اندازهٔ ثانیه‌هایی که Retry-After می‌گوید صبر کنید و بعد دوباره بفرستید.	منتظر Retry-After بمانید
TOKEN_SCOPE	403	این توکن دسترسیِ لازم برای این مسیر را ندارد: دوباره نفرستید؛ صاحب حساب باید توکنی با این دسترسی بسازد.	تکرار نکنید
SCOPE_DISABLED	403	توکن این دسترسی را دارد، اما لُب فعلاً این نوع دسترسی را خاموش کرده است: بعداً دوباره امتحان کنید.	بعداً دوباره امتحان کنید
PENDING_APPROVAL	403	حساب صاحب توکن هنوز در انتظار تأیید است و فعلاً نمی‌توان از آن استفاده کرد: پس از تأیید دوباره امتحان کنید.	بعداً دوباره امتحان کنید
SCOPE_UNAVAILABLE	400	برنامه توکنی با دسترسی‌ای که فعلاً خاموش است نمی‌سازد: از دسترسی‌هایی که صفحهٔ ساخت توکن نشان می‌دهد انتخاب کنید و وقتی بقیه روشن شدند توکن دیگری بسازید.	بعداً دوباره امتحان کنید
TOKEN_REQUIRED	400	whoami یک توکن API را توصیف می‌کند و این درخواست از مرورگری آمد که وارد حساب شده بود: آن را با هدر Authorization: Bearer lobbe_… فراخوانی کنید.	درخواست را اصلاح کنید
VALIDATION	400	درخواست درست نیست (فیلد، پارامتر یا هدری جا افتاده، ناشناخته یا خارج از محدوده است) و message می‌گوید کدام: پیش از فرستادن دوباره اصلاحش کنید.	درخواست را اصلاح کنید
NOT_FOUND	404	چیزی با این شناسه در دسترس این توکن نیست (ناشناخته، حذف‌شده، متعلق به دیگری یا بیرون از دسترس توکن، همه یک‌جور دیده می‌شوند): همین شناسه را دوباره نفرستید.	تکرار نکنید
INTERNAL	500	لُب نتوانست یکی از مرحله‌های کار را در سمت خودش تمام کند (ذخیرهٔ صدا یا ذخیرهٔ پاسخ): بعداً دوباره امتحان کنید؛ با همان Idempotency-Key، تکرار هرگز دو بار هزینه نمی‌گیرد.	بعداً دوباره امتحان کنید
INTERNAL_ERROR	500	در سمت لُب خطای پیش‌بینی‌نشده‌ای رخ داد: بعداً دوباره امتحان کنید؛ با همان Idempotency-Key، تکرار هرگز دو بار هزینه نمی‌گیرد.	بعداً دوباره امتحان کنید
INVALID_AUDIO	400	این فایل صدایی نیست که لُب بتواند بخواند: آن را با قالب دیگری یا از خروجی دیگری بفرستید.	درخواست را اصلاح کنید
AUDIO_INCOMPLETE	400	فایل صوتی ناقص است (پایان فایل نیامده؛ معمولاً کپی یا ارسالی که زود متوقف شده): فایل کامل را بفرستید.	درخواست را اصلاح کنید
UPLOAD_TOO_LARGE	413	فایل از سقف ارسال بزرگ‌تر است، سقفی که whoami در limits.maxUploadMb می‌گوید: فایل کوچک‌تری بفرستید.	درخواست را اصلاح کنید
RECORDING_TOO_LONG	413	صدا از بیشترین طولی که یک جلسه می‌تواند داشته باشد بلندتر است، طولی که whoami در limits.maxRecordingMinutes می‌گوید: آن را چند تکه کنید و تکه‌ها را بفرستید.	درخواست را اصلاح کنید
VIDEO_UPLOAD_DISABLED	409	ارسال ویدیو خاموش است: به‌جای آن صدای جلسه را بفرستید.	درخواست را اصلاح کنید
VIDEO_UNAVAILABLE	503	لُب فعلاً نمی‌تواند صدا را از ویدیو جدا کند: بعداً دوباره امتحان کنید یا خود صدا را بفرستید.	بعداً دوباره امتحان کنید
VIDEO_NO_AUDIO	400	این ویدیو صدا ندارد و چیزی برای تبدیل به رونوشت نیست: فایلی با صدا بفرستید.	درخواست را اصلاح کنید
VIDEO_UNREADABLE	400	این ویدیو خوانده نمی‌شود: آن را با قالب دیگری بفرستید یا صدایش را بفرستید.	درخواست را اصلاح کنید
ATTACHMENT_TYPE	400	پیوست فایل PDF، PPTX یا DOCX نیست: یکی از این‌ها را بفرستید یا بدون پیوست بفرستید.	درخواست را اصلاح کنید
ATTACHMENT_TOO_LARGE	413	پیوست از ۱۰ مگابایت بزرگ‌تر است: فایل کوچک‌تری بفرستید.	درخواست را اصلاح کنید
DAILY_LIMIT_REACHED	429	صاحب حساب به سقف روزانهٔ خود لُب رسیده است (برای جلسه‌ها، یا برای پرسش‌های ۲۴ ساعت گذشته) و هیچ توکنی آن را بالا نمی‌برد: بعداً دوباره امتحان کنید، و اگر Retry-After آمد پس از آن.	بعداً دوباره امتحان کنید
INSUFFICIENT_MINUTES	402	موجودی صاحب حساب برای این کار کافی نیست: details.requiredMinutes می‌گوید چند دقیقه لازم است و details.balanceMinutes فقط برای توکنی با دسترسی account:read می‌آید؛ تا صاحب حساب دقیقه نخریده است دوباره نفرستید.	تکرار نکنید
TOKEN_DAILY_CAP	429	این کار توکن را از سقف دقیقهٔ روزانه‌اش می‌گذراند (details مقدارهای capMinutes، usedMinutes و requiredMinutes را دارد): به اندازهٔ Retry-After صبر کنید؛ اگر نیامده باشد، صبر کمکی نمی‌کند و صاحب حساب باید سقف را در «اتصال‌ها» بالا ببرد.	منتظر Retry-After بمانید
IDEMPOTENCY_KEY_IN_USE	409	توکن دیگری از این حساب، یا خود برنامه، پیش‌تر این Idempotency-Key را به کار برده است و کلید برای همیشه از آنِ صاحب حساب می‌ماند (برای جلسه در کل حساب، برای پرسش روی همان جلسه یا سری): کلید تصادفی تازه‌ای بفرستید، نه هش فایل.	درخواست را اصلاح کنید
UPLOAD_IN_PROGRESS	503	درخواست قبلی‌ای با همین Idempotency-Key هنوز در حال ذخیرهٔ صدای خود است: به اندازهٔ Retry-After صبر کنید و همان درخواست را دوباره بفرستید تا همان جلسه را برگرداند.	منتظر Retry-After بمانید
NOT_NAMING	409	جلسه در مرحلهٔ نام‌گذاری گوینده‌ها منتظر نیست (از آن گذشته یا هنوز به آن نرسیده است): به‌جای رد کردن دوباره، وضعیتش را بخوانید.	تکرار نکنید
NOT_FAILED	409	فقط جلسهٔ ناموفق را می‌توان دوباره اجرا کرد و این جلسه ناموفق نیست: به‌جای آن وضعیتش را بخوانید.	تکرار نکنید
NOT_READY	409	جلسه هنوز آماده نیست؛ در پاسخ مسیر جلسهٔ کامل، details کنار error می‌آید نه درون آن، و details.status می‌گوید جلسه در چه مرحله‌ای است: وضعیت را دوباره بخوانید و وقتی READY شد جلسهٔ کامل را بخوانید.	بعداً دوباره امتحان کنید
ASK_DISABLED	409	پرسش فعلاً در لُب خاموش است: بعداً دوباره امتحان کنید.	بعداً دوباره امتحان کنید
ASK_NOT_READY	409	این جلسه هنوز لُب ندارد و چیزی برای پرسیدن نیست: صبر کنید تا وضعیتش READY شود.	بعداً دوباره امتحان کنید
PRICE_ABOVE_MAX	409	هزینهٔ پاسخ از maxMinutes شما بیشتر است (details مقدارهای minutes و maxMinutes را دارد) و هزینه‌ای گرفته نشد: maxMinutes را بالا ببرید یا نپرسید.	درخواست را اصلاح کنید
SERIES_ASK_TOO_FEW	409	برای پرسش از یک سری دست‌کم ۲ جلسهٔ آماده لازم است: وقتی سری به این تعداد رسید دوباره امتحان کنید.	بعداً دوباره امتحان کنید
GENERATE_FAILED	502	مدل این بار نتوانست پاسخ دهد و هزینه‌ای گرفته نشد: بعداً با همان Idempotency-Key دوباره امتحان کنید.	بعداً دوباره امتحان کنید
SERIES_LIMIT	409	صاحب حساب همین حالا ۵۰ سری دارد، بیشترین تعدادی که یک حساب می‌تواند داشته باشد: دوباره نفرستید؛ صاحب حساب باید اول یکی را در برنامه حذف کند.	تکرار نکنید
SERIES_NAME_TAKEN	409	صاحب حساب سری دیگری با همین نام دارد (بزرگی و کوچکی حروف نام را متفاوت نمی‌کند): نام دیگری انتخاب کنید.	درخواست را اصلاح کنید
MEMORY_DISABLED	409	حافظه در لُب خاموش است، پس نکته‌ای را نمی‌توان ویرایش یا حذف کرد (خواندن فهرست خالی برمی‌گرداند): بعداً دوباره امتحان کنید.	بعداً دوباره امتحان کنید
MEMORY_DUPLICATE	409	صاحب حساب همین نکته را در همان دسته دارد: به‌جای این، همان نکته را ویرایش یا حذف کنید.	درخواست را اصلاح کنید
CURSOR_EXPIRED	410	نشانگر از ۳۰ روزی که رویدادها نگه داشته می‌شوند قدیمی‌تر است، یا به پیش از بازگردانی داده‌های لُب برمی‌گردد: نخست با after=latest نشانگر تازه‌ای بگیرید، بعد عقب‌ماندگی را از listReadyRecordings جبران کنید و سپس از همان نشانگر تازه به بعد بخوانید.	درخواست را اصلاح کنید