خطاها و سهمیه
کدهای خطا، سهمیه روزانه و retry در API Servix
ساختار خطای API Servix، وضعیت های 400، 401، 403، 404، 417، 429 و 500، سهمیه روزانه و روش امن retry و عیب یابی را بخوانید.
کلاینت قابل اعتماد فقط پاسخ 200 را پردازش نمی کند. وضعیت HTTP و فیلد code را ثبت کنید، requestId را برای پیگیری نگه دارید و فقط خطاهای موقت را با تاخیر دوباره امتحان کنید.
ساختار مشترک خطا
{
"status": 429,
"code": "DAILY_LIMIT_EXCEEDED",
"message": "this account has reached its daily limit!",
"timestamp": "2026-04-13T10:24:00Z",
"path": "/api/v1/assets/USD_RLS",
"requestId": "4f8e7f9d-7c76-4e3f-a8f4-7d1b2b351f21"
}- status نسخه عددی وضعیت HTTP است؛
- code کد پایدارتر برای تصمیم برنامه است؛
- message توضیح قابل ثبت برای عیب یابی است و نباید تنها مبنای منطق برنامه باشد؛
- timestamp زمان پاسخ خطا و path مسیر درخواست است؛
- requestId شناسه پیگیری است. همین مقدار در هدر X-Request-Id پاسخ نیز برمی گردد.
معنی وضعیت های مهم
| HTTP | کدهای رایج | اقدام پیشنهادی |
|---|---|---|
| 400 | VALIDATION_FAILED، MISSING_REQUEST_PARAMETER، INVALID_REQUEST_PARAMETER، BAD_REQUEST | قالب تاریخ، پارامتر و بدنه را اصلاح کنید؛ retry خودکار نکنید. |
| 401 | AUTHENTICATION_FAILED | وجود، قالب و معتبر بودن API Key را بررسی کنید. |
| 403 | ACCOUNT_EXPIRED، ACCESS_DENIED | وضعیت حساب یا اشتراک و سطح دسترسی را بررسی کنید. |
| 404 | ASSET_NOT_FOUND | کد نماد را با supported تطبیق دهید یا نبود داده آن روز را مدیریت کنید. |
| 417 | INVALID_DATE_RANGE | ترتیب تاریخ و حداکثر بازه ۳۱ روز را اصلاح کنید. |
| 429 | DAILY_LIMIT_EXCEEDED | تا دوره سهمیه بعدی صبر یا پلن مناسب تری انتخاب کنید. |
| 500 | INTERNAL_SERVER_ERROR | با backoff محدود دوباره تلاش و در تداوم خطا requestId را گزارش کنید. |
سهمیه چگونه مصرف می شود؟
درخواست های محافظت شده مسیرهای /api/v1/assets برای حساب پولی سهمیه روزانه مصرف می کنند؛ endpoint کاتالوگ supported نیز در همین گروه است. تعداد درخواست را در سمت خود اندازه بگیرید و از polling جداگانه برای هر کاربر یا هر widget پرهیز کنید. نتیجه را در بک اند cache و بین مصرف کنندگان خود به اشتراک بگذارید.
تفاوت سهمیه با محدودیت لحظه ای
وضعیت 429 در قرارداد فعلی پایان سهمیه روزانه حساب را نشان می دهد. مستندات نرخ ثابت در ثانیه یا هدر زمان reset اعلام نمی کند؛ بنابراین مقدار یا زمان reset را حدس نزنید. اگر برای حجم بالا برنامه ریزی می کنید، پلن ها را بر اساس درخواست روزانه مقایسه یا از پشتیبانی درباره نیاز خود سوال کنید.
الگوی retry امن
- 400، 401، 403، 404 و 417 را بدون تغییر ورودی تکرار نکنید؛
- 429 را در حلقه سریع retry نکنید؛ مصرف را متوقف و وضعیت اشتراک را بررسی کنید؛
- برای 500 و خطاهای شبکه، تعداد تلاش را محدود و تاخیر نمایی همراه jitter استفاده کنید؛
- برای درخواست های تاریخی، هر قطعه موفق را ذخیره کنید تا پس از خطا از ابتدا شروع نشود؛
- کلید API، بدنه محرمانه یا داده کاربر را در لاگ خطا ننویسید.
استفاده از requestId
می توانید هدر X-Request-Id با حروف، عدد، نقطه، خط تیره یا زیرخط و طول حداکثر ۱۲۸ کاراکتر بفرستید. اگر مقدار معتبر نباشد، سرور شناسه جدید می سازد. هنگام تماس با پشتیبانی، requestId، زمان، مسیر، وضعیت و code را ارسال کنید؛ API Key کامل را ارسال نکنید.
چک لیست عیب یابی
- در راهنمای احراز هویت قالب هدر را با نمونه مقایسه کنید؛
- کد را با کاتالوگ نمادها بررسی کنید؛
- برای تاریخچه، قالب و طول بازه را طبق راهنمای داده تاریخی کنترل کنید؛
- درخواست را با مجموعه Postman رسمی بازتولید کنید؛
- اگر خطای 500 ادامه داشت، از صفحه تماس requestId را گزارش کنید.