تمام خطاها با ساختار یکسان و کد HTTP مناسب برگردانده میشوند.
400invalid_rangeپارامتر نامعتبر
مقدار range باید یکی از 24h، 7d، 30d یا 90d باشد.
{
"error": "invalid_range",
"message": "range must be one of 24h, 7d, 30d, or 90d"
}
400invalid_assetsفهرست دارایی نامعتبر
پارامتر assets خالی است، بیش از ۵۰ شناسه دارد یا شناسه‌ای با قالب نادرست دارد.
{
"error": "invalid_assets",
"message": "assets must list at least one asset id"
}
400invalid_assetدارایی نامعتبر
پارامترهای from و to در تبدیل مبلغ ارسال نشده یا assetId ناشناخته است.
{
"error": "invalid_asset",
"message": "Unknown asset: xyz"
}
400invalid_amountمقدار نامعتبر
amount باید عدد اعشاری نامنفی با ارقام انگلیسی و بدون جداکننده هزارگان باشد.
{
"error": "invalid_amount",
"message": "amount must be a non-negative decimal number such as 500 or 2.5"
}
400invalid_parameterپارامتر قیمت طلا نامعتبر
در قیمت طلای زینتی، weight یا wage ارسال نشده یا یکی از پارامترها خارج از محدوده مجاز است. پیام خطا نام پارامتر را می‌گوید.
{
"error": "invalid_parameter",
"message": "weight is required: grams greater than 0 and no greater than 100000, e.g. 3.2"
}
400invalid_dateتاریخ نامعتبر
تاریخ در نرخ یک تاریخ قابل خواندن نیست، در تقویم وجود ندارد (مثل ۳۰ اسفند سال غیرکبیسه) یا در آینده است.
{
"error": "invalid_date",
"message": "1404-12-30 is not a valid Jalali date"
}
400invalid_bodyبدنه نامعتبر
بدنه درخواست ساخت پیش‌فاکتور JSON معتبری از نوع شیء نیست.
{
"error": "invalid_body",
"message": "Request body must be a JSON object"
}
401unauthorizedکلید نامعتبر
هدر X-App-Key ارسال نشده، کلید اشتباه است یا ابطال/چرخش شده است.
{
"error": "unauthorized",
"message": "Invalid or missing API key"
}
401key_expiredکلید منقضی شده
تاریخ انقضایی که برای این کلید در داشبورد تعیین شده گذشته است. تاریخ را تمدید کنید یا کلید جدیدی بسازید.
{
"error": "key_expired",
"message": "This API key expired at 2026-10-01T20:29:59.000Z"
}
402trial_expiredپایان دوره آزمایشی
۵ روز آزمایشی حساب شما تمام شده است. برای ادامه، از داشبورد یک پلن تهیه کنید یا کیف پول پرداخت به‌ازای مصرف را شارژ کنید.
{
"error": "trial_expired",
"message": "Your free trial has ended. Choose a plan or top up a pay-as-you-go wallet at https://arzhaam.ir/dashboard/billing to keep using the API."
}
402subscription_expiredپایان اشتراک
دوره اشتراک و ۳ روز مهلت تمدید آن تمام شده است. از داشبورد اشتراک را تمدید کنید یا کیف پول را شارژ کنید.
{
"error": "subscription_expired",
"message": "Your subscription has expired. Renew or top up a pay-as-you-go wallet at https://arzhaam.ir/dashboard/billing to keep using the API."
}
402insufficient_balanceموجودی ناکافی کیف پول
پلن فعالی ندارید و موجودی کیف پول پرداخت به‌ازای مصرف برای این درخواست کافی نیست. کیف پول را شارژ کنید یا پلن بخرید.
{
"error": "insufficient_balance",
"message": "Your pay-as-you-go wallet balance is too low. Top up at https://arzhaam.ir/dashboard/billing or choose a plan to keep using the API."
}
403forbiddenدسترسی محدود
پلن شما به این بازه تاریخچه یا قابلیت دسترسی ندارد.
{
"error": "forbidden",
"message": "History range 30d requires Pro plan or higher"
}
403ip_not_allowedIP مجاز نیست
کلید به فهرست IP یا بازه CIDR مشخصی محدود شده و درخواست از آدرس دیگری آمده است.
{
"error": "ip_not_allowed",
"message": "Requests from 203.0.113.7 are not allowed for this API key"
}
403referrer_not_allowedدامنه مجاز نیست
کلید به دامنههای مشخصی محدود شده و هدر Origin یا Referer درخواست با آن‌ها مطابقت ندارد یا ارسال نشده است.
{
"error": "referrer_not_allowed",
"message": "Requests from evil.example are not allowed for this API key"
}
404asset_not_foundدارایی یافت نشد
assetId در مسیر یا یکی از شناسه‌های پارامتر assets معتبر نیست.
{
"error": "asset_not_found",
"message": "Unknown asset: xyz"
}
404date_unavailableنرخی برای این تاریخ نیست
برای آن روز نرخی ثبت نشده است؛ معمولاً چون تاریخ پیش از شروع بایگانی نرخ‌هاست. پیام خطا اولین تاریخ موجود را می‌گوید.
{
"error": "date_unavailable",
"message": "Rates are available from 1405-04-20 (2026-07-11) onwards"
}
404quote_not_foundپیش‌فاکتور یافت نشد
شناسه پیش‌فاکتور وجود ندارد، بیش از ۳۰ روز از انقضایش گذشته یا متعلق به حساب دیگری است.
{
"error": "quote_not_found",
"message": "Unknown quote: qt_8f3a61c2d4e5b7a9c0d1e2f3"
}
409quote_redeemedپیش‌فاکتور قبلاً مصرف شده
این پیش‌فاکتور یکبار مصرف شده و دوباره قابل استفاده نیست.
{
"error": "quote_redeemed",
"message": "Quote qt_8f3a61c2d4e5b7a9c0d1e2f3 was already redeemed at 2026-10-09T20:19:44.020Z"
}
410quote_expiredپیش‌فاکتور منقضی شده
زمان اعتبار پیش‌فاکتور تمام شده است. یک پیش‌فاکتور تازه با نرخ جدید بسازید.
{
"error": "quote_expired",
"message": "Quote qt_8f3a61c2d4e5b7a9c0d1e2f3 expired at 2026-10-09T20:26:02.511Z; create a new one"
}
429rate_limit_exceededمحدودیت درخواست
سقف پلن شما پر شده است. هدر Retry-After و فیلد retryAfter تعداد ثانیه تا درخواست بعدی را نشان می‌دهند.
{
"error": "rate_limit_exceeded",
"message": "Rate limit exceeded",
"retryAfter": 42
}
429key_quota_exceededسهمیه کلید تمام شده
سهمیه روزانه یا ماهانه‌ای که برای همین کلید تعیین کرده‌اید پر شده است (مستقل از سقف پلن). Retry-After زمان آغاز روز یا ماه بعد به وقت تهران را نشان میدهد.
{
"error": "key_quota_exceeded",
"message": "This API key has used its daily quota of 1000 requests",
"retryAfter": 3600
}
503rates_unavailableمنبع در دسترس نیست
سرویس نرخ موقتاً در دسترس نیست. چند ثانیه بعد دوباره تلاش کنید.
{
"error": "rates_unavailable",
"message": "Rates service is temporarily unavailable"
}