همهٔ خطاها یک شکل دارند: وضعیت HTTP معنادار، شیء error با code ثابت (برای کد شما)، message فارسی (برای انسان)، status و لینک docs که به همین صفحه میآید. بسته به خطا، فیلدهای کمکی هم اضافه میشود.
{
"error": {
"code": "origin_not_allowed",
"message": "درخواست از دامنهٔ «evil.example» برای این اپ مجاز نیست. دامنهٔ ثبتشده: example.com",
"status": 403,
"docs": "https://netarz.ir/docs/fx/errors#origin_not_allowed",
"origin": "evil.example",
"allowed": ["example.com", "*.example.com"]
}
}
{
"error": {
"code": "validation_failed",
"message": "The amount field must be at least 0.",
"status": 422,
"errors": { "amount": ["The amount field must be at least 0."] },
"docs": "https://netarz.ir/docs/fx/errors#validation_failed"
}
}
فهرست کدها
| HTTP | code | معنا و راهحل |
|---|---|---|
| 400 | invalid_request | پارامتر نامعتبر (توضیح در message). |
| 400 | unknown_currency | در convert: from یا to ناشناخته (param میگوید کدام). |
| 400 | invalid_range | مقدار range خارج از 1h/24h/7d/30d/90d/1y/3y/5y/10y/all. |
| 400 | invalid_time | from/to/at تاریخ معتبری نیست (ISO 8601 یا Unix timestamp). |
| 400 | invalid_window | from بعد از to است. |
| 400 | interval_too_small | interval کمتر از حداقل (۵ دقیقه). |
| 400 | period_too_small | period کندل کمتر از ۱۵ دقیقه. |
| 400 | too_many_points | بازه ÷ interval بیشتر از سقف نقاط؛ interval بزرگتر بدهید. |
| 400 | archive_is_daily | interval یا period کمتر از یک روز برای پیش از شروع ثبت درونروزی (فیلد intraday_since)؛ 1d یا بزرگتر بدهید. |
| 400 | invalid_date | تاریخ archive به شکل YYYY-MM-DD (میلادی یا شمسی) نیست. |
| 400 | invalid_webhook_url | آدرس وبهوک https نیست یا به آدرس داخلی اشاره میکند. |
| 401 | missing_api_key | هدر Authorization / X-API-Key نیست. |
| 401 | invalid_api_key | کلید وجود ندارد. |
| 401 | app_disabled | اپ از پنل متوقف شده. |
| 402 | pro_required | امکان فقط در پرو (فیلد upgrade_url): تاریخچه، آرشیو، OHLC، آمار، snapshot، هشدار و استریم. |
| 403 | app_suspended | اپ توسط نِت اَرز معلق شده؛ دلیل در message. |
| 403 | domain_not_verified | مالکیت دامنه تأیید نشده. |
| 403 | origin_not_allowed | Origin/Referer با دامنههای اپ نمیخواند (فیلدهای origin و allowed). |
| 403 | origin_required | بدون Origin/Referer و بدون IP مجاز؛ IP سرور را در پنل مجاز کنید. |
| 403 | ip_not_allowed | IP درخواست در فهرست مجاز نیست (فیلد ip). |
| 403 | outside_history_window | snapshot یا archive خارج از پنجرهٔ تاریخچهٔ طرح (فیلد earliest). |
| 403 | alert_limit_reached | سقف هشدار هر اپ پر است. |
| 404 | unknown_currency | کد ارز در فهرست نیست (rates/history/ohlc/stats/snapshot). |
| 404 | no_data | برای این بازه یا لحظه دادهای ثبت نشده. |
| 404 | alert_not_found | هشدار با این شناسه برای این اپ نیست. |
| 422 | validation_failed | اعتبارسنجی ورودی (فیلد errors به تفکیک پارامتر). |
| 429 | rate_limit_exceeded | محدودیت در دقیقه (اپ یا IP). Retry-After را بخوانید. |
| 429 | daily_quota_exceeded | سهمیهٔ روزانه تمام شده (فیلدهای quota, used, plan). |
| 429 | too_many_failed_attempts | کلیدهای اشتباه زیاد از این IP؛ چند دقیقه صبر کنید. |
| 429 | too_many_streams | استریم همزمان بیش از حد برای این اپ. |
| 503 | service_disabled | سرویس موقتاً توسط نِت اَرز خاموش است. |
کد را بررسی کنید، نه پیام را
پیامها ممکن است بهتر شوند؛ codeها ثابت میمانند. برای ۴۲۹ به Retry-After و برای ۴۰۲ به upgrade_url نگاه کنید.