# فهرست خطاها
در پاسخهای ناموفق، مقدار meta.isSuccess برابر false است و سه فیلد meta.code، meta.errorType و meta.errorMessage وضعیت خطا را مشخص میکنند.
# کدهای وضعیت
| کد | نوع (errorType) | پیام پیشفرض | توضیح |
|---|---|---|---|
| 0 | Success | عملیات با موفقیت انجام شد | درخواست موفق بود |
| 1 | ServerError | خطایی در سرور رخ داده است | خطای داخلی؛ با trackId به پشتیبانی اطلاع دهید |
| 2 | BadRequest | پارامتر های ارسالی معتبر نیستند | خطای اعتبارسنجی؛ meta.errors را بخوانید |
| 3 | NotFound | یافت نشد | رکورد یا سرویس درخواستی وجود ندارد |
| 4 | ListEmpty | لیست خالی است | نتیجهای برای پارامترهای ارسالی یافت نشد |
| 5 | LogicError | خطایی در پردازش رخ داد | خطای منطقی؛ مثلاً موجودی ناکافی |
| 6 | UnAuthorized | خطای احراز هویت | توکن نامعتبر، منقضی یا ارسالنشده است |
| 7 | Unavailable | سامانه هم اکنون در دسترس نمیباشد | سامانهی مرجع در دسترس نیست؛ بعداً دوباره تلاش کنید |
| 8 | EmailConfirmationFailed | ایمیل شما تایید نشده است | ایمیل حساب تأیید نشده است |
| 9 | Inaccessible | عدم دسترسی | حساب غیرفعال است یا این سرویس برای شما فعال نشده |
| 10 | SmsVerificationTimeout | مدت زمان اعتبار کد تایید به پایان رسیده است | مهلت رمز یکبارمصرف تمام شده است |
| 11 | InvalidSmsVerification | کد تایید اشتباه میباشد | رمز یکبارمصرف نادرست است |
| 12 | InvalidPostalCode | کد پستی یافت نشد | کد پستی نامعتبر یا ثبتنشده است |
| 13 | FailedShahkarInquiry | خطا در استعلام شاهکار | استعلام شاهکار ناموفق بود |
| 14 | RequestTimeOut | درخواست منقضی شده است | مهلت پاسخ سامانهی مرجع تمام شد |
| 15 | ProviderError | خطایی رخ داده است، لیست خطا را بررسی کنید | تأمینکننده خطا برگرداند؛ meta.errors را بخوانید |
# نگاشت به وضعیت HTTP
| وضعیت HTTP | حالت رایج |
|---|---|
| ۲۰۰ | درخواست پردازش شد؛ نتیجه را از meta.isSuccess بخوانید |
| ۴۰۰ | خطای اعتبارسنجی، trackId تکراری یا موجودی ناکافی |
| ۴۰۱ | توکن نامعتبر یا منقضی |
| ۴۰۳ | حساب غیرفعال، سرویس فعالنشده، یا IP مجاز نیست |
| ۴۰۴ | سرویس یا رکورد یافت نشد |
| ۵۰۲ | خطای تأمینکنندهی بیرونی |
| ۵۰۳ | سرویس موقتاً در دسترس نیست |
| ۵۰۰ | خطای داخلی زرینهاب |
# خطاهای پرتکرار
trackId تکراری — هر trackId فقط یکبار قابل استفاده است. برای هر فراخوانی یک UUID تازه بسازید. (توضیح بیشتر)
موجودی ناکافی — پیش از فراخوانی، اعتبار حساب بررسی میشود. حساب خود را شارژ کنید یا آستانهی هشدار موجودی را در پنل تنظیم کنید.
عدم دسترسی به سرویس — سرویس موردنظر باید برای حساب شما فعال شده باشد. برای فعالسازی با پشتیبانی تماس بگیرید.
IP غیرمجاز — اگر برای حساب خود IP ثبت کردهاید، درخواست باید از همان IPها ارسال شود. (امنیت و محدودسازی IP)
# واکنش درست به هر خطا
meta.code | واکنش |
|---|---|
| 2 | ورودی را اصلاح کنید؛ تلاش مجدد بدون تغییر بیفایده است |
| 3 | به کاربر اطلاع دهید؛ تلاش مجدد نکنید |
| 4 | نتیجهای وجود ندارد؛ خطا محسوب نمیشود |
| 5 | پیام را نمایش دهید؛ برای نمونه موجودی ناکافی |
| 6 | توکن را تازه کنید و یک بار دوباره تلاش کنید |
| 7 | با تأخیر فزاینده تلاش مجدد کنید |
| 9 | با پشتیبانی تماس بگیرید؛ تلاش مجدد بیفایده است |
| 10 / 11 | جریان رمز یکبارمصرف را از ابتدا اجرا کنید |
| 14 | وضعیت را با سرویس پیگیری بررسی کنید، سپس تصمیم بگیرید |
| 15 | meta.errors را بخوانید؛ در صورت نیاز با advanced تلاش کنید |
| 1 | با trackId تیکت ثبت کنید |
# قاعدهی تلاش مجدد
یک درخواست را با همان trackId دوباره ارسال نکنید — رد میشود. پس از قطع ارتباط هم بدون بررسی وضعیت، همان استعلام را با trackId جدید تکرار نکنید — ممکن است دوبار هزینه شود.
مسیر درست پس از قطع ارتباط یا انقضای مهلت:
- وضعیت درخواست را با
/api/v5/Tracking/GetStatusو همانtrackIdاستعلام کنید. - اگر درخواست پردازش شده بود، نتیجه را با
/api/v5/Tracking/GetDetailsبگیرید. - فقط اگر درخواستی ثبت نشده بود، فراخوانی تازه با
trackIdجدید انجام دهید.
برای خطاهای گذرا (کدهای ۷ و ۱۴) تأخیر فزاینده بهکار ببرید؛ مثلاً ۲، ۵ و ۱۵ ثانیه و حداکثر سه تلاش.
# نرمالسازی ورودی فارسی
بخش بزرگی از خطاهای اعتبارسنجی و عدم تطابق نام از ورودی فارسی میآید. پیش از ارسال:
- ارقام فارسی و عربی (
۱۲۳،١٢٣) را به ارقام انگلیسی تبدیل کنید. - «ي» عربی را به «ی» فارسی و «ك» عربی را به «ک» فارسی تبدیل کنید.
- فاصلههای اضافی ابتدا و انتهای رشته را حذف کنید.
- کد ملی را با صفرهای ابتدایی و بهطول ۱۰ رقم ارسال کنید.
- شماره کارت و شبا را بدون فاصله و خط تیره ارسال کنید.
# اطلاعات لازم برای تیکت پشتیبانی
- مقدار
meta.trackId - مسیر سرویس (مثلاً
/api/v5/KYC/CheckShahkar) - زمان تقریبی درخواست
- مقدار
meta.codeوmeta.errorMessage
بدنهی کامل پاسخ سرویسهای هویتی را در لاگ متنی ننویسید. برای هر فراخوانی فقط مسیر سرویس، trackId، meta.code، زمان پاسخ و موفق/ناموفق بودن را ثبت کنید.