پرش به مطلب اصلی

وضعیت بودجه با GET /v1/budget/me

این مسیر به کلاینت می‌گوید با همان کلید یا توکنی که درخواست می‌فرستد، از هر سقف بودجه چقدر باقی مانده است. با آن می‌توانید پیش از ارسال درخواست‌های سنگین، یا بعد از دریافت خطای budget_exceeded، وضعیت را به کاربر نشان دهید.

هر کلید یا توکن درگاه که بتواند درخواست مدل بفرستد، می‌تواند این مسیر را بخواند. پاسخ ذخیره نمی‌شود (Cache-Control: no-store).

درخواست​

curl https://api.godarai.ir/v1/budget/me \
-H "Authorization: Bearer $GODARAI_API_KEY"

پاسخ​

{
"object": "budget_status",
"unit": "credit",
"rules": [
{
"rule_id": "support-daily-budget",
"name": "بودجه روزانه پشتیبانی",
"scope": "team",
"limit": "250.00",
"spent": "112.40",
"remaining": "137.60",
"window_end": "2026-10-18T00:00:00Z",
"on_exceed": "block"
}
],
"tenant_balance": {
"remaining": "1830.25",
"reserved": "4.10",
"window_end": "2026-11-01T00:00:00Z"
}
}
فیلدمعنی
unitهمیشه credit. همه مقدارها رشته‌های کردیت با دو رقم اعشارند.
rules[].scopeنوع تفکیک قانون؛ مثل tenant، user، team یا virtualaccount.
rules[].spentکردیت مصرف‌شده در پنجره فعلی همان قانون.
rules[].remainingسقف منهای مصرف قطعی و رزروهای در جریان.
rules[].window_endزمان شروع پنجره بعدی قانون.
rules[].on_exceedblock اگر پر شدن سقف درخواست را رد کند، alert اگر فقط ثبت شود.
tenant_balanceکردیتی که فضای کاری در ماه جاری هنوز می‌تواند خرج کند. فقط برای فراخواننده‌ای که دسترسی خواندن صورت‌حساب (billing:read یا billing:manage) یا نقش مدیر دارد برگردانده می‌شود.

چه قوانینی فهرست می‌شوند؟​

  • فقط قوانین فعالی که به هویت فراخواننده می‌خورند؛ یعنی کل فضای کاری، کاربر، تیم یا اکانت مجازی.
  • قوانینی که «به‌ازای هر مدل» یا «به‌ازای فراداده» تفکیک می‌شوند فهرست نمی‌شوند، چون برای هر مقدار پنجره جدا دارند.
  • شرط‌های وابسته به خود درخواست، مثل مدل یا فراداده، بدون درخواست قابل ارزیابی نیستند. قانونی که به هویت فراخواننده بخورد، صرف‌نظر از این شرط‌ها فهرست می‌شود.

خطاها​

وضعیتکدتوضیح
401unauthorizedکلید یا توکن معتبر نیست.
503billing_unavailableوضعیت بودجه موقتا قابل خواندن نیست؛ کمی بعد دوباره تلاش کنید.

ادامه مسیر​