بررسی موجودی کاربر
GET /v1/user/balance
مستندات
توضیح
موجودی کیف پول فعلی کاربر را دریافت کنید. این endpoint برای بررسی موجودی قبل از انجام درخواستهای گرانقیمت یا نمایش موجودی در رابط کاربری مفید است.
یک درخواست GET بدون بدنه و بدون پارامتر است؛ فقط همان کلید API را میفرستید و یک عدد به ریال میگیرید. اگر موجودی تمام شود، درخواستهای بعدی شما با خطای 402 رد میشوند، پس این ارزانترین راه برای جلوگیری از آن است.
پارامترهای درخواست
این endpoint نیاز به پارامترهای درخواست ندارد. فقط باید توکن احراز هویت را فراهم کنید.
احراز هویت: الزامی - API Token در هدر Authorization
نمونههای درخواست و پاسخ
curl https://api-ai.hibanacloud.ir/v1/user/balance \ -H "Authorization: Bearer YOUR_API_KEY"فیلدهای پاسخ
| فیلد | نوع | توضیح |
|---|---|---|
| object | string | همیشه "user.balance" |
| balance | number | موجودی کاربر به ریال ایرانی (IRR) |
| currency | string | همیشه "IRR" (ریال ایرانی) |
کدهای خطا
401 Unauthorized
توکن API نامعتبر یا گمشده است
{ "error": { "message": "Invalid or missing API key", "type": "invalid_request_error" }}404 Not Found
کاربر یافت نشد
{ "error": { "message": "User not found", "type": "invalid_request_error" }}برای 401 شکل هدر Authorization را با احراز هویت بسنجید. فهرست کامل کدها و شکل استاندارد پاسخ خطا در مدیریت خطاها است.
بهترین شیوهها
- بررسی موجودی قبل از درخواست: همیشه موجودی کافی را تأیید کنید قبل از انجام درخواستهای گرانقیمت
- هشدار موجودی کم: هنگام پایین آمدن موجودی زیر حد مشخصی به کاربر هشدار دهید
- کشکردن موجودی: موجودی را بهصورت موقت در کلاینت ذخیره کنید و بهصورت دورهای بروزرسانی کنید
- مدیریت خطای 402: خطای "موجودی ناکافی" را بگیرید و از کاربر برای شارژ کردن بخواهید
نکته:
این endpoint موجودی کیف پول را برمیگرداند، نه سقف بودجهٔ ماهانهٔ یک کلید API. اگر کیف پول موجودی دارد ولی درخواستها همچنان 402 میگیرند، احتمالاً سقف بودجهٔ همان کلید پر شده است، تفاوت insufficient_funds و budget_exceeded در مدیریت خطاها توضیح داده شده است.
برای کم کردن سرعت مصرف موجودی، بخش نکات صرفهجویی در قیمتگذاری و صورتحساب را ببینید.