رفتن به محتوا

حل مشکلات

راهنمایی برای حل مشکلات رایج

مستندات

401 Unauthorized

مشکل: API خطای 401 برمی‌گرداند

علل:

  • کلید API نامعتبر یا منقضی شده
  • هدر Authorization نادرست
  • هدر Authorization گمشده

راه‌حل:

# CORRECT: فرمت صحیحAuthorization: Bearer YOUR_API_TOKEN # WRONG: فرمت غلطAuthorization: YOUR_API_TOKEN  # Bearer گمشدهAuthorization: "Bearer YOUR_API_TOKEN"  # علامت نقل‌قول

شکل درست هدر و همهٔ حالت‌های غلطش در احراز هویت آمده است؛ اگر کلید را گم کرده‌اید، از دریافت کلید API یکی تازه بسازید.

429 Rate Limited

مشکل: درخواست‌های متکرر کند شدند

علل:

  • درخواست‌های بیش‌تر از حد مجاز
  • موجودی محدودیت کافی

راه‌حل:

# بررسی محدودیت قبل از درخواستremaining = int(response.headers['X-RateLimit-Remaining'])if remaining < 5:    print(f"تنها {remaining} درخواست باقی. صبر می‌کنیم...")    time.sleep(60) # exponential backoff را پیاده‌سازی کنید# درخواست‌های concurrent را کاهش دهید# batch processing استفاده کنید

نمونهٔ کامل exponential backoff و معنی هر هدر X-RateLimit-* در محدودیت نرخ درخواست است. برای اینکه تلاش مجدد باعث کسر هزینهٔ دوباره نشود، بخش کلید یکتاسازی همان صفحه را ببینید.

402 موجودی ناکافی

مشکل: درخواست به دلیل موجودی کم رد شد

علل:

  • موجودی حساب = 0
  • درخواست منفرد از موجودی بیش‌تر

راه‌حل:

  1. موجودی را در داشبورد بررسی کنید
  2. حساب خود را شارژ کنید
  3. قیمت‌گذاری را بررسی کنید
  4. max_tokens یا مدل‌های ارزان‌تر را استفاده کنید

موجودی را از داخل برنامه هم می‌شود خواند: بررسی موجودی کاربر. اگر کیف پول موجودی دارد ولی باز هم 402 می‌گیرید، سقف بودجهٔ ماهانهٔ همان کلید پر شده است؛ تفاوت دو حالت در مدیریت خطاها آمده و راه‌های کم کردن هزینه در قیمت‌گذاری و صورت‌حساب.

Connection Timeout

مشکل: درخواست معلق یا timeout می‌شود

علل:

  • مشکل اتصال شبکه
  • سرور بیش‌بار
  • timeout خیلی کوتاه

راه‌حل:

# timeout را افزایش دهیدresponse = requests.post(    url,    json=payload,    timeout=(5, 60)  # 5s connect, 60s read) # retry را اجرا کنیدtime.sleep(random.uniform(1, 5))

پاسخ‌های بلند طبیعتاً طول می‌کشند؛ اگر منتظر ماندن آزاردهنده است، به‌جای بالا بردن timeout از استریم پاسخ (SSE) استفاده کنید تا متن از همان ثانیهٔ اول شروع به رسیدن کند.

Model Not Found

مشکل: کد مدل وجود ندارد

راه‌حل:

# لیست مدل‌های دسترس‌پذیر را بررسی کنیدcurl https://api-ai.hibanacloud.ir/v1/models \  -H "Authorization: Bearer YOUR_API_TOKEN" # نام مدل را بررسی کنید (case-sensitive)# مدل را فعال‌سازی کنید# از طریق پشتیبانی تماس بگیرید

همان فهرست، خوانا و با قیمت هر مدل، در لیست مدل‌ها هست. کد مدل دقیقاً همان رشته‌ای است که در فیلد model درخواست می‌گذارید، به Chat Completions نگاه کنید.

Streaming قطع می‌شود

مشکل: پاسخ جریانی به‌طور ناگهانی متوقف می‌شود

علل:

  • اتصال قطع شد
  • proxy buffering فعال است
  • timeout خیلی کوتاه

راه‌حل:

# timeout برای streaming را افزایش دهیدresponse = requests.post(    url,    json={"stream": True, ...},    stream=True,    timeout=(5, 120)  # 120s read timeout) # chunk‌های ناقص را مدیریت کنیدtry:    for line in response.iter_lines():        # پردازش...except requests.exceptions.ChunkedEncodingError:    print("WARNING: Stream قطع شد")

اگر پاسخ به‌جای تدریجی یکجا می‌رسد، معمولاً یک proxy میانی در حال buffer کردن است. شکل درست مصرف stream و فیلدهای هر chunk در استریم پاسخ (SSE) آمده است.

تولید تصویر ناموفق

مشکل: تولید تصویر خطا برمی‌گرداند

علل:

  • مدل اشتباه (فقط DALL-E از OpenAI)
  • prompt نامناسب
  • ترکیب size/quality پشتیبانی‌نشده
  • موجودی کافی نیست

راه‌حل:

# مدل را تأیید کنیدmodels = requests.get(    'https://api-ai.hibanacloud.ir/v1/models',    headers={'Authorization': f'Bearer {api_key}'}).json() # مدل توصیه‌شده برای تولید تصویر# model: "nano-banana-pro" # size یک نسبت ابعاد است، نه اندازه به پیکسل# 1:1  2:3  3:4  4:5  9:16  3:2  4:3  16:9  21:9  5:4

پارامترهای واقعی این endpoint سه‌تا بیشتر نیستند (prompt، model و size) و همه با مقادیر مجازشان در تولید تصویر با AI فهرست شده‌اند. اگر می‌خواهید تصویری را به مدل بفرستید (نه بسازید)، صفحهٔ درست ورودی تصویر است.

سند فرستادم، جواب خالی است

مشکل: پاسخ HTTP 200 است ولی مدل انگار سند را ندیده

علل:

  • مدل استدلالی است و تمام بودجه صرف استدلال شده (محتوای خالی، finish_reason برابر length)
  • ارائه‌دهندهٔ آن مدل اصلاً سند نمی‌پذیرد
  • پیوست اصلاً به مدل نرسیده است

راه‌حل:

# اول این عدد را نگاه کنید، نه متن پاسخ را.print(response.usage.prompt_tokens) # یک PDF یک‌صفحه‌ای این را از ۱۰۰۰ بالاتر می‌برد (اندازه‌گیری‌شده: ۱۶۸۷).# اگر نزدیک ۵۰ ماند، سند به مدل نرسیده است. # مدل‌های استدلالی برای سند به بودجهٔ صریح نیاز دارند:response = client.chat.completions.create(    model="gpt-5-nano",    messages=messages,    max_completion_tokens=2000,    reasoning_effort="low",   # بدون این، محتوا خالی برمی‌گردد)

شکل درست بخش file، جدول مدل‌هایی که سند می‌خوانند و همهٔ محدودیت‌ها در ورودی فایل آمده است. اگر کد خطا گرفتید، مدیریت خطاها جدول جدا برای خطاهای پیوست دارد.

دریافت کمک

  1. لاگ‌ها را بررسی کنید: پاسخ API و پیام خطا را مشاهده کنید
  2. endpoint را تست کنید: از cURL برای جداسازی مشکلات استفاده کنید.
  3. پشتیبانی: کلید API (masked)، جزئیات درخواست، timestamp و stack trace را ارائه دهید.

دستور cURL آماده برای گام دوم در احراز هویت و نمونه کدها هست. اگر کد خطا دارید ولی نمی‌دانید یعنی چه، مدیریت خطاها جدول کامل کدها و پیام‌ها را دارد.