خطاها
خطاها از پوشش استاندارد استفاده می‌کنند. کد وضعیت HTTP نوع خطا را نشان می‌دهد و
بدنه یک code پایدار و قابل‌خواندن توسط ماشین به‌همراه پیام دوزبانه دارد:
{ success: false, error: { code, message_fa, message_en, details }, meta }تصمیم‌گیری را بر اساس error.code انجام دهید، نه متن پیام. مقدار details ممکن
است زمینهٔ بیشتری داشته باشد (مثلاً { limit, window } برای محدودیت نرخ).
کدهای رایج
| وضعیت | کد | چه زمانی |
|---|---|---|
| 401 | AUTH_INVALID_TOKEN | کلید نبود، نامعتبر، باطل‌شده یا منقضی |
| 403 | SCOPE_DENIED | تولید خارج از scopeهای کلید |
| 403 | PLAN_REQUIRED | پلن دسترسی API ندارد |
| 403 | ACCOUNT_BANNED | حساب صاحب کلید مسدود است |
| 404 | (منبع) | شناسهٔ ناشناخته یا متعلق به دیگری |
| 409 | JOB_NOT_CANCELABLE | لغو کاری که در صف/در حال پردازش نیست |
| 409 | JOB_NOT_RETRYABLE | تلاش مجدد کاری که ناموفق نبوده |
| 422 | INVALID_SCOPES | نام scope ناشناخته هنگام ساخت کلید |
| 422 | INVALID_WEBHOOK_EVENTS | رویدادهای webhook خالی یا ناشناخته |
| 429 | RATE_LIMITED | عبور از rpm/rpd کلید (یا rpm کاربر) |
خطاهای اعتبارسنجی بدنهٔ درخواست نیز با کد 422 و جزئیات فیلدها برمی‌گردند.