مرجع
کدهای وضعیت HTTP و کدهای خطا
همه پاسخ‌های ممکن API قیمت زویکس: کدهای وضعیت HTTP، کد هر خطا، علت و راه‌حل، و هدرهای پاسخ.
شکل پاسخ خطا
همه خطاها (به‌جز مسیری که اصلاً وجود ندارد) این شکل را دارند. برنامه خود را روی code بنویسید، نه متن پیام:
{
"error": {
"code": "ip_not_allowed",
"message": "این IP برای این کلید مجاز نیست"
}
}کدهای وضعیت HTTP
| کد | نام | معنی |
|---|---|---|
| 200 | OK | موفق؛ پاسخ در data است. |
| 400 | Bad Request | پارامتر نامعتبر. |
| 401 | Unauthorized | کلید نیامده یا نامعتبر است. |
| 402 | Payment Required | اشتراک فعال نیست؛ تمدید کنید. |
| 403 | Forbidden | کلید درست است ولی این درخواست مجاز نیست (IP، دامنه، اپ اندروید یا پلن). |
| 404 | Not Found | نماد یا مسیر وجود ندارد. |
| 429 | Too Many Requests | سقف دقیقه، سهمیه روزانه یا تعداد اتصال زنده پر شده؛ Retry-After را ببینید. |
| 500 | Internal Server Error | خطای سرور؛ با فاصله دوباره تلاش کنید. |
| 503 | Service Unavailable | موقتاً در دسترس نیست؛ بعد از Retry-After تلاش کنید. |
همه کدهای خطا
401
api_key_requiredکلید ارسال نشده- چه وقت
- هیچ‌کدام از
X-API-Key،Authorization: Bearerیاapi_keyدر درخواست نیست. - راه‌حل
- کلید را در هدر
X-API-Keyبفرستید.
401
invalid_api_keyکلید نامعتبر یا باطل- چه وقت
- کلید اشتباه تایپ شده، باطل شده یا وجود ندارد.
- راه‌حل
- کلید را از داشبورد کپی کنید یا کلید تازه بسازید.
402
subscription_expiredاشتراک تمام شده- چه وقت
- پلن فعالی برای حساب نیست (تمام شده یا هنوز نخریده‌اید).
- راه‌حل
- از داشبورد پلن را تمدید کنید؛ کلیدها بلافاصله دوباره کار می‌کنند.
403
client_suspendedحساب غیرفعال- چه وقت
- حساب شما توسط پشتیبانی غیرفعال شده است.
- راه‌حل
- با پشتیبانی زویکس تماس بگیرید.
403
ip_not_allowedIP مجاز نیست- چه وقت
- برای کلید فهرست IP تعریف شده و درخواست از IP دیگری آمده.
- راه‌حل
- IP سرور را در «IPهای مجاز» کلید اضافه کنید.
403
origin_not_allowedدامنه مجاز نیست- چه وقت
- کلید به دامنه‌های مشخصی محدود است و درخواست (یا قاب ویجت) از سایت دیگری است.
- راه‌حل
- دامنه را در «دامنه‌های مجاز» کلید اضافه کنید.
403
app_not_allowedاپ مجاز نیست- چه وقت
- کلید به اپ‌های اندروید مشخصی محدود است و هدرهای
X-Android-PackageوX-Android-Certنیامده یا با اپ ثبت‌شده نمی‌خواند. - راه‌حل
- هدرها را از خود اپ بفرستید (راهنمای اندروید) و SHA-256 گواهی امضای نسخه انتشار (Play App Signing) را در کلید ثبت کنید.
403
plan_feature_missingامکان در پلن نیست- چه وقت
- ارسال زنده یا ویجت در پلن شما نیست.
- راه‌حل
- پلن را به حرفه‌ای یا سازمانی ارتقا دهید.
403
symbol_not_in_planنماد در پلن نیست- چه وقت
- پلن شما به نمادهای مشخصی محدود است.
- راه‌حل
- نمادهای پلن را با
/v1/symbolsببینید یا پلن را ارتقا دهید.
403
history_not_in_planتاریخچه در پلن نیست- چه وقت
- پلن شما تاریخچه ندارد.
- راه‌حل
- پلنی با تاریخچه انتخاب کنید.
403
history_range_not_in_planبازه بیش از سقف پلن- چه وقت
daysبیشتر از بازه تاریخچه پلن است.- راه‌حل
daysرا کمتر کنید یا پلن را ارتقا دهید.
404
symbol_not_foundنماد وجود ندارد- چه وقت
- نماد اشتباه است.
- راه‌حل
- شناسه درست را از
/v1/symbolsبردارید (حروف کوچک انگلیسی).
429
rate_limitedسقف درخواست در دقیقه- چه وقت
- بیش از سقف پلن در یک دقیقه درخواست داده‌اید.
- راه‌حل
- به هدر
Retry-After(ثانیه) احترام بگذارید، پاسخ‌ها را چند ثانیه کش کنید یا از/v1/streamاستفاده کنید.
429
daily_quota_exceededسهمیه روزانه تمام شد- چه وقت
- مصرف امروز (به وقت تهران) به سهمیه پلن رسیده.
- راه‌حل
- تا نیمه‌شب تهران صبر کنید یا پلن را ارتقا دهید؛
X-Quota-Remainingرا پایش کنید.
429
too_many_streamsاتصال زنده زیاد- چه وقت
- بیش از ۵ اتصال هم‌زمان
/v1/streamبا یک کلید. - راه‌حل
- یک اتصال در سرور بگیرید و بین کاربران خودتان پخش کنید.
500
internalخطای داخلی- چه وقت
- مشکل پیش‌بینی‌نشده در سرور.
- راه‌حل
- با فاصله دوباره تلاش کنید؛ اگر ادامه داشت با شناسه درخواست (
X-Request-Id) به پشتیبانی خبر دهید.
503
service_disabledسرویس موقتاً متوقف- چه وقت
- سرویس‌دهی API برای نگهداری موقتاً خاموش است.
- راه‌حل
- بعد از
Retry-Afterدوباره تلاش کنید.
مسیری که وجود ندارد پاسخ ۴۰۴ متنی (نه JSON) می‌گیرد؛ آدرس را با /v1/… بررسی کنید.
هدرهای پاسخ
| هدر | معنی |
|---|---|
X-RateLimit-Limit | سقف درخواست در دقیقه پلن شما |
X-Quota-Limit | سهمیه روزانه (فقط وقتی پلن سهمیه دارد) |
X-Quota-Remaining | باقی‌مانده سهمیه امروز |
X-Plan | نام پلن (URL-encoded) |
X-Local-Free-Remaining | فقط برای درخواست از صفحه‌ای روی localhost یا 127.0.0.1: باقی‌مانده درخواست‌های رایگان توسعه امروز |
Retry-After | در پاسخ‌های ۴۲۹ و ۵۰۳: چند ثانیه صبر کنید |
X-Request-Id | شناسه درخواست برای پیگیری با پشتیبانی |
نمونه مدیریت خطا
const res = await fetch(url, { headers: { "X-API-Key": key } });
const body = await res.json();
if (!res.ok) {
switch (body.error.code) {
case "invalid_api_key": // کلید را در تنظیمات برنامه بررسی کنید
case "subscription_expired": // به مدیر خبر دهید تا تمدید کند
alertAdmin(body.error.message); break;
case "rate_limited": // Retry-After ثانیه صبر کنید
await sleep(Number(res.headers.get("Retry-After") ?? 60) * 1000); break;
default:
console.error(res.status, body.error.code, body.error.message);
}
}