کدهای خطا و مرجع وضعیت
راهنمای جامع کدهای خطای Smart Money API، کدهای وضعیت HTTP و مراحل عیبیابی. پاسخهای خطا را درک کنید و مشکلات یکپارچهسازی را به سرعت حل کنید.
کدهای موفقیت 2xx
پاسخهای موفقیت نشان میدهند که درخواست با موفقیت پردازش شده است.
| کد | وضعیت | معنی |
|---|---|---|
| 200 | OK | درخواست موفقیتآمیز بود. بدنه پاسخ شامل دادههای درخواستی است. |
| 201 | Created | منبع با موفقیت ایجاد شد. پاسخ شامل منبع جدید است. |
| 204 | No Content | درخواست موفقیتآمیز بود اما هیچ محتوایی برای بازگشت وجود ندارد (مثلاً DELETE). |
مثال پاسخ 200
JSON
{
"success": true,
"data": {
"total": 42,
"positions": [...],
"pagination": {
"page": 1,
"limit": 50
}
},
"timestamp": "2026-03-21T14:35:22Z"
}
کدهای خطای سمت کلاینت 4xx
خطاهای سمت کلاینت نشان میدهند که درخواست نادرست یا نامعتبر است. درخواست خود را اصلاح کنید و دوباره امتحان کنید.
| کد | وضعیت | علت |
|---|---|---|
| 400 | Bad Request | نحو درخواست نادرست است. پارامترهای کوئری، هدرها و بدنه درخواست را بررسی کنید. |
| 401 | Unauthorized | اعتبارنامههای احراز هویت وجود ندارند یا نامعتبر هستند. کلید API یا توکن JWT خود را بررسی کنید. |
| 402 | Payment Required | پرداخت اشتراک شما ناموفق بود. اطلاعات صورتحساب را در حساب خود بهروزرسانی کنید. |
| 403 | Forbidden | احراز هویت شدهاید اما مجوز دسترسی به این منبع را ندارید. طرح شما شامل این ویژگی نیست. |
| 404 | Not Found | منبع وجود ندارد. آدرس URL و پارامترهای نقطه پایانی را بررسی کنید. |
| 429 | Too Many Requests | محدودیت نرخ превыرشده است. قبل از تلاش مجدد صبر کنید. هدر Retry-After را بررسی کنید. |
| 422 | Unprocessable Entity | اعتبارسنجی ناموفق بود. پارامترهای درخواست نامعتبر هستند یا فیلدهای الزامی وجود ندارند. |
مثالهای خطای احراز هویت
کلید API وجود ندارد (401)
JSON
{
"success": false,
"error": {
"code": "AUTH_MISSING_KEY",
"message": "اعتبارنامههای احراز هویت ارائه نشدهاند.",
"resolution": "کلید API خود را در هدر Authorization قرار دهید: Authorization: Bearer sk_live_..."
},
"timestamp": "2026-03-21T14:35:22Z"
}
کلید API نامعتبر (401)
JSON
{
"success": false,
"error": {
"code": "AUTH_INVALID_KEY",
"message": "کلید API نامعتبر یا منقضی شده است.",
"resolution": "یک کلید API جدید از کنسول خود در https://smartmoneyapi.com/console ایجاد کنید."
},
"timestamp": "2026-03-21T14:35:22Z"
}
محدودیت نرخ (429)
وقتی سهمیه API شما بیش از حد باشد، سرور 429 Too Many Requests را برمیگرداند. هدرهای پاسخ را برای اطلاعات محدودیت نرخ بررسی کنید:
هدرهای HTTP
X-Requests-Remaining: 0
X-Requests-Limit: 200
X-Requests-Reset: 1711116922
Retry-After: 3600
پاسخ خطای محدودیت نرخ
JSON
{
"success": false,
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "محدودیت درخواست روزانه API (10) بیش از حد شده است.",
"resolution": "به طرح Trader (29 دلار در ماه، 1,000 درخواست در روز) یا Pro (79 دلار در ماه، 5,000 درخواست در روز) ارتقا دهید.",
"reset_at": "2026-03-22T09:00:00Z"
},
"timestamp": "2026-03-21T14:35:22Z"
}
خطاهای اعتبارسنجی (422)
خطاهای اعتبارسنجی زمانی رخ میدهند که پارامترهای درخواست شما نامعتبر هستند یا فیلدهای الزامی وجود ندارند.
JSON
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "اعتبارسنجی درخواست ناموفق بود.",
"details": [
{
"field": "symbol",
"error": "جفت معاملاتی نامعتبر. فرمت مورد انتظار: BTCUSDT"
},
{
"field": "min_position_size",
"error": "باید یک عدد مثبت باشد"
}
],
"resolution": "خطاهای اعتبارسنجی را اصلاح کنید و دوباره امتحان کنید."
},
"timestamp": "2026-03-21T14:35:22Z"
}
کدهای خطای سمت سرور 5xx
خطاهای سمت سرور نشاندهنده مشکلی در سمت ما هستند. این خطاها موقت هستند و معمولاً به سرعت حل میشوند. منطق بازگشت نمایی را پیادهسازی کنید.
| کد | وضعیت | اقدام |
|---|---|---|
| 500 | Internal Error | خطای غیرمنتظره سرور. با منطق بازگشت نمایی دوباره امتحان کنید. |
| 502 | Bad Gateway | مختل شدن موقت سرویس. پس از چند ثانیه دوباره امتحان کنید. |
| 503 | Service Unavailable | تعمیرات یا قطعی موقت. صفحه وضعیت را بررسی کنید. پس از بازه Retry-After دوباره امتحان کنید. |
| 504 | Gateway Timeout | درخواست زمان زیادی طول کشید. ممکن است سرور آن را پردازش کرده باشد. بررسی کنید که درخواست idempotent باشد. |
مثال خطای سرور (503)
JSON
{
"success": false,
"error": {
"code": "SERVICE_UNAVAILABLE",
"message": "سرویس به دلیل تعمیرات موقتاً در دسترس نیست.",
"resolution": "لطفاً پس از 5 دقیقه دوباره امتحان کنید. وضعیت را در https://status.smartmoneyapi.com دنبال کنید."
},
"timestamp": "2026-03-21T14:35:22Z"
}
راهنمای عیبیابی
401 Unauthorized - کلید API نامعتبر
مشکل: دریافت خطاهای 401 حتی با وجود کلید API.
راهحلها:
- بررسی کنید که کلید API در هدر Authorization با پیشوند "Bearer" قرار دارد
- بررسی کنید که کلید API شما منقضی یا لغو نشده باشد
- مطمئن شوید که از کلید صحیح (تولید، آزمایشی یا توسعه) استفاده میکنید
- اگر کلید فعلی گم شده است، یک کلید API جدید از کنسول خود ایجاد کنید
403 Forbidden - ویژگی در دسترس نیست
مشکل: دریافت خطاهای 403 در برخی نقاط پایانی.
راهحلها:
- سطح API خود را بررسی کنید. برخی نقاط پایانی نیاز به طرحهای Trader یا Pro دارند
- طرح خود را در /pricing.html ارتقا دهید تا به ویژگیهای پریمیوم دسترسی پیدا کنید
- بررسی کنید که کلید API دارای محدودههای مورد نیاز فعال باشد
- اگر فکر میکنید باید دسترسی داشته باشید، با پشتیبانی تماس بگیرید
429 Too Many Requests - محدودیت نرخ
مشکل: دریافت خطاهای 429 و محدودیت نرخ.
راهحلها:
- منطق بازگشت نمایی را پیادهسازی کنید (1 ثانیه، 2 ثانیه، 4 ثانیه و غیره صبر کنید)
- پاسخها را کش کنید تا از درخواستهای تکراری API جلوگیری کنید
- برای دادههای بلادرنگ به جای پرسوجو از نقاط پایانی REST از WebSocket استفاده کنید
- برای سهمیههای بالاتر طرح خود را ارتقا دهید (Trader 400 در روز، Pro 4,000 در روز)
- در صورت امکان چندین پرسوجو را در یک درخواست دستهبندی کنید
400 Bad Request - پارامترهای نامعتبر
مشکل: دریافت خطاهای 400 با درخواستهای نادرست.
راهحلها:
- مستندات API را برای پارامترهای الزامی و اختیاری بررسی کنید
- نوع پارامترها را بررسی کنید (رشتهها در مقابل اعداد، آرایهها در مقابل اشیا)
- مطمئن شوید که JSON معتبر و بهدرستی فرمت شده است
- از آدرسهای URL صحیح نقاط پایانی با پارامترهای مسیر مناسب استفاده کنید
- غلطهای املایی در نام پارامترهای کوئری را بررسی کنید
خطاهای سرور 5xx - قطعیهای موقت
مشکل: دریافت خطاهای 500، 502، 503 یا 504.
راهحلها:
- وضعیت سرویس را در https://status.smartmoneyapi.com بررسی کنید
- پیادهسازی تلاش مجدد خودکار با تاخیر نمایی (حداکثر 5-10 تلاش)
- 30-60 ثانیه قبل از تلاش مجدد برای خطاهای 503 صبر کنید
- از هدر Retry-After برای تعیین زمان تلاش مجدد استفاده کنید
- برای اطلاعرسانی حوادث، به صفحه وضعیت مشترک شوید
قالب پاسخ خطا
تمام پاسخهای خطا از یک قالب ثابت پیروی میکنند:
JSON
{
"success": false,
"error": {
"code": "ERROR_CODE",
"message": "پیام خطای قابل فهم برای انسان",
"details": {...},
"resolution": "مراحل حل مشکل"
},
"timestamp": "2026-03-21T14:35:22Z"
}
نیاز به کمک بیشتر دارید؟
مستندات API ما را بررسی کنید یا با ارائه کد خطا و جزئیات درخواست خود با پشتیبانی تماس بگیرید.
مرجع API