خطاها

یک قالب برای همه خطاها

هر خطای API، صرف‌نظر از مسیر و کد وضعیت، همین ساختار را دارد:

{
  "msg": "Bad request",
  "reasons": [
    "amount must be greater than the minimum withdrawal"
  ]
}

فیلد	یعنی چه
msg	پیام خوانا و کلی
reasons	فهرست دلایل مشخص، یا null

⚠

reasons می‌تواند null باشد. کدی که مستقیم رویش پیمایش کند، روزی که خطایی بدون دلیل مشخص برگردد خودش خطا می‌دهد — آن هم درست وقتی که دارید به خطای دیگری رسیدگی می‌کنید.

این متن‌ها را برای توسعه‌دهنده نوشته‌ایم، نه برای کاربر نهایی. آن‌ها را لاگ کنید، اما به کاربر پیام خودتان را به فارسی نشان دهید.

کدهای وضعیت

کد	یعنی چه	تلاش مجدد؟
400	بدنه یا پارامتر نامعتبر	خیر — باگ سمت شماست
401	توکن نامعتبر یا منقضی	بله — یک بار، پس از تازه کردن توکن
403	سازمان شما این دسترسی را ندارد	خیر — نگاه کنید به دسترسی‌ها
404	منبع وجود ندارد	خیر
409	تعارض؛ معمولاً x-transaction-uuid تکراری با پارامتر متفاوت	خیر — نگاه کنید به تراکنش‌ها
410	نشانی موقعیت وثیقه منقضی شده	خیر — موقعیت تازه بسازید
5xx	خطای سمت زربان	بله — با عقب‌نشینی نمایی

قاعده تلاش مجدد

⚠

تلاش مجدد روی یک فراخوانی جابه‌جاکننده پول باید همان x-transaction-uuid تلاش اول را بفرستد. اگر پاسخ submit با خطای شبکه یا 5xx از دست برود، تراکنش ممکن است در سمت زربان ساخته شده و تنها پاسخ آن نرسیده باشد؛ سرور درخواست تکراری را از روی همین مقدار تشخیص می‌دهد و تراکنش دوم ثبت نمی‌کند.

برای مسیرهای خواندنی و 5xx:

• عقب‌نشینی نمایی با اندکی تصادفی‌سازی — مثلاً ۱، ۲، ۴ و ۸ ثانیه.
• سقف تلاش بگذارید. تلاش بی‌پایان، خطای گذرا را به قطعی طولانی بدل می‌کند.
• 4xx را هرگز تکرار نکنید (به‌جز 401 که یک بار پس از تازه کردن توکن).

محدودیت نرخ

⚠

اعداد دقیق محدودیت نرخ، فهرست نشانی‌های آی‌پی که وب‌هوک از آن‌ها می‌آید، و اینکه آیا به آی‌پی ثابت خروجی نیاز دارید یا نه، همه در پیکربندی سازمان شما تعیین می‌شوند. این موارد را هنگام جذب از تماس سازمانی خود بگیرید.

تا وقتی عدد مشخصی ندارید، محتاط باشید: فراخوانی‌های فهرست‌گیری را با صفحه‌بندی معقول بزنید، نرخ‌ها را کش کنید، و به‌جای فراخوانی مکرر، از وب‌هوک استفاده کنید.

عیب‌یابی

لاگ درخواست‌ها

زربان هر درخواست احراز هویت‌شده روی سازمان شما را ثبت می‌کند:

curl -sS "https://hd.zarban.io/tenants/PLN/audit-logs" \
  -H "Authorization: Bearer $ZARBAN_TOKEN"

هر وقت مطمئن نیستید درخواستتان اصلاً به زربان رسیده یا نه، سراغ همین‌جا بیایید.

لاگ تحویل وب‌هوک

curl -sS "https://hd.zarban.io/webhooks/PLN/logs?limit=20" \
  -H "Authorization: Bearer $ZARBAN_TOKEN"

نگاه کنید به وب‌هوک‌ها.

چند خطای رایج

نشانه	علت محتمل
401 روی همه چیز، بلافاصله پس از استقرار	grantType را client_credentials نوشته‌اید؛ مقدار درست ClientCredentials است.
401 روی /oauth/refresh	توکن تازه‌سازی چرخیده و شما نسخه قبلی را ذخیره کرده‌اید.
403 روی یک محصول	آن دسترسی برای سازمان شما فعال نیست.
409 روی submit	همان UUID با پارامتر متفاوت. باگ سمت شماست.
موجودی کمتر از انتظار کاربر	locked را از balance کم نکرده‌اید.
واریز کاربر نرسیده	memo را به کاربر نشان نداده‌اید، یا آدرس منسوخ را نمایش داده‌اید.
امضای وب‌هوک نمی‌خواند	روی JSON تجزیه‌شده حساب کرده‌اید، نه روی بدنه خام.