خطاها و محدودیت‌های API
HTTP و نتیجهٔ عملیات
موفقیت درخواست HTTP به‌تنهایی موفقیت عملیات را ثابت نمی‌کند. برخی endpointها با HTTP 200، نتیجه‌ای مثل success: false و توضیح در message، error یا data.message برمی‌گردانند. ساختار پاسخ endpoint مورد استفاده را بخوانید.
| وضعیت | بررسی پیشنهادی |
|---|---|
| 400 | ورودی و قالب فیلدها را با قرارداد endpoint مقایسه کنید. |
| 401 | هدر Authorization: Token ... و Token مدیریت hub را بررسی کنید. |
| 403 | دسترسی حساب، نقش و محدودیت درخواست‌ها را بررسی کنید؛ صرفاً به معنی کلید اشتباه نیست. |
| 404 | مسیر، نام سرویس و عضویت حساب را بررسی کنید؛ منابع خارج از دسترسی نیز ممکن است پیدا نشوند. |
| 5xx | متن پاسخ را ثبت و وضعیت سرویس را بررسی کنید؛ درخواست تغییردهنده را بی‌بررسی تکرار نکنید. |
Token مدیریت چابکان و API Key هوش مصنوعی دو نوع کلید متفاوت‌اند. همچنین قبولنش دن دعوت تیمی می‌تواند باعث شود سرویس برای حساب دیده نشود.
محدودیت نرخ
محدودیت‌ها برای endpointها یکسان نیستند. برای مسیرهای این راهنما:
| مسیر | سقف درخواست |
|---|---|
GET /services/ | ۶۰ درخواست در دقیقه |
GET /services/{main_name}/logs/ | ۲۰۰ درخواست در دقیقه |
GET /services/{main_name}/deploy-logs/ | ۲۰۰ درخواست در دقیقه |
POST /services/{main_name}/deploy/ | ۵ درخواست در دقیقه |
GET /cloudservers/ | ۳۰ درخواست در دقیقه |
در محدودسازی فعلی، پاسخ منع دسترسی می‌تواند 403 باشد؛ همیشه منتظر 429 نباشید. در برنامهٔ خود فاصلهٔ بین درخواست‌ها را رعایت کنید و پس از محدودشدن، درخواست‌های پی‌درپی نفرستید.
تکرار درخواست و تشخیص نتیجه
خواندن اطلاعات یا لاگ را با فاصله و تعداد تلاش محدود تکرار کنید. برای ارسال استقرار یا عملیات تغییر سرویس، ابتدا نتیجهٔ درخواست قبلی را از پنل یا endpoint مربوطه بررسی کنید.
برخی مسیرهای قدیمی مدیریت سرویس مانند start/، stop/، restart/ و delete/ با متد GET اثر تغییردهنده دارند. متد GET را در این API به‌تنهایی معیار خواندنی‌بودن عملیات ندانید و برای آن‌ها retry خودکار عمومی قرار ندهید.
برای پیگیری، متد و مسیر درخواست، وضعیت HTTP، متن خطای بدون اطلاعات محرمانه و زمان وقوع را نگه دارید. Token و هدر احراز هویت را در لاگ عمومی یا تیکت ثبت نکنید.