محدودیت‌ها و امنیت

محدودیت‌های نرخ

پاسخ‌های ۴۲۹ هدر Retry-After (ثانیه) دارند:

HTTP/1.1 429 Too Many Requests
Retry-After: 5
Content-Type: application/json

{"error":{"message":"محدودیت 60 درخواست در دقیقه برای این کلید. کمی صبر کنید.","type":"rate_limit_error","code":"rate_limit_exceeded"}}

همهٔ این مقادیر با یک تیکت و بر اساس نیاز واقعی قابل افزایش‌اند؛ RPM و همزمانی را می‌توان برای هر کلید/حساب جداگانه تنظیم کرد.

محدودیت‌های اندازه

برای درخواست‌های غیراستریم، در صورت خطای اتصال یا پاسخ‌های ۵۰۲/۵۰۳/۵۲۹ ارائه‌دهنده، نِت اَرز به‌طور خودکار ۱ بار تلاش مجدد می‌کند. تلاش‌های ناموفق هزینه‌ای ندارند.

مدیریت تلاش مجدد در کلاینت

import time, random
from openai import OpenAI, RateLimitError, APIStatusError

client = OpenAI(base_url="https://netarz.ir/api/ai/v1", api_key="sk-ntz-v1-...", max_retries=0)

def ask(messages, attempts=5):
    for i in range(attempts):
        try:
            return client.chat.completions.create(model="gpt-4o-mini", messages=messages, max_tokens=300)
        except RateLimitError as e:                       # 429: RPM، همزمانی، سقف رایگان، ظرفیت ارائه‌دهنده
            wait = float(e.response.headers.get("Retry-After", 2 ** i)) + random.random()
            time.sleep(wait)
        except APIStatusError as e:
            if e.status_code == 402:                      # اعتبار — تلاش مجدد بی‌فایده است
                raise
            if e.status_code >= 500:                      # خطای ارائه‌دهنده — رایگان بود، دوباره تلاش کنید
                time.sleep(2 ** i)
                continue
            raise
    raise RuntimeError("giving up")

امنیت کلیدها

فهرست IP مجاز

برای هر کلید می‌توانید فهرستی از IPها تعریف کنید؛ درخواست از IP دیگر با ip_not_allowed (۴۰۳) رد می‌شود. هر خط یکی از این شکل‌ها:

185.12.34.56          # یک IP دقیق
185.12.34.            # پیشوند: هر IP که با این شروع شود
185.12.0.0/16         # CIDR (IPv4)

مدل‌های مجاز

هم در سطح پروژه و هم در سطح کلید می‌توانید مدل‌های مجاز را محدود کنید (فهرست خالی = همه). یک کلید فقط به مدل‌هایی دسترسی دارد که هم پروژه و هم خودش اجازه داده‌اند؛ در غیر این صورت model_not_allowed (۴۰۳).

سقف هزینه و بودجه

• سقف هزینهٔ کلید: مجموع مصرف کلید در کل عمرش؛ با رسیدن به آن key_spend_limit_reached (۴۰۲).
• بودجهٔ ماهانهٔ پروژه: project_budget_exceeded (۴۰۲) — بر اساس ماه میلادی جاری.
• تاریخ انقضا: پس از آن کلید با api_key_expired (۴۰۱) رد می‌شود؛ برای کلیدهای موقت (تست، پیمانکار) مفید است.

چرخش کلید

1. کلید جدید با همان محدودیت‌ها بسازید.
2. کلید جدید را در سرویس‌ها مستقر کنید و از last_used_at کلید قدیمی در پنل مطمئن شوید که دیگر استفاده نمی‌شود.
3. کلید قدیمی را باطل کنید (بازگشت‌ناپذیر). اگر فقط می‌خواهید موقتاً قطع کنید، «غیرفعال» کنید.

در سمت نِت اَرز

• کلیدها فقط به‌صورت هش SHA-256 ذخیره می‌شوند و مقدار کامل پس از ساخت قابل بازیابی نیست.
• متن پیام‌ها و پاسخ‌ها ذخیره نمی‌شود؛ فقط فراداده (مدل، توکن‌ها، وضعیت، IP، زمان) برای صورت‌حساب و امنیت.
• ارتباط با همهٔ ارائه‌دهندگان از سرورهای نِت اَرز و روی TLS انجام می‌شود؛ فیلد user شما پیش از ارسال با شناسهٔ ناشناس حساب جایگزین می‌شود.
• هر حساب یک سقف مصرف روزانهٔ ایمنی (در صورت تعیین) و کل سرویس یک سقف ظرفیت روزانه دارد؛ در حالت نادر تکمیل ظرفیت، خطای daily_capacity_reached (۵۰۳) برمی‌گردد.