معمولی

رفع اشکال اتصال به بنفش

هفت تا خطایی که بیشتر از همه موقع وصل‌کردن یه ابزار به بنفش می‌بینی — یعنی چی و چطور درستش کنی.

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

آدرس سرویس اشتباهه

اگه base URL رو دستی تایپ کردی یا از یه جای قدیمی کپی کردی، درخواست اصلاً به بنفش نمی‌رسه — connection refused یا timeout می‌گیری، نه یه پیام خطا از بنفش (چون سرور مقصد اصلاً بنفش نیست).

راه‌حل: آدرس رو دوباره از صفحه‌ی «کلیدهای API» کپی کن — هیچ‌وقت دستی تایپش نکن یا از یه فایل قدیمی برنداری. این آدرس بین محیط‌ها فرق می‌کنه، پس یه نسخه‌ی ذخیره‌شده از قبل می‌تونه دیگه معتبر نباشه.

اگه به جای اون خطاها HTTP 404 گرفتی، معمولاً شکل آدرس با ابزارت نمی‌خونه. کارت «آدرس سرویس» دو شکل داره: Claude Code و SDKهای Anthropic آدرس رو بدون /v1 می‌خوان (خودشون /v1/messages رو اضافه می‌کنن)؛ ابزارهای سازگار با OpenAI (SDKهای OpenAI، Cursor، Cline، aider و…) با /v1 (خودشون فقط /chat/completions رو اضافه می‌کنن). ردیف درست رو برای ابزارت کپی کن. (Cursor فقط با پلن پولی خودش اجازه‌ی کلید و آدرس دلخواه رو می‌ده؛ با پلن رایگان از Cline توی VS Code استفاده کن.)

خطای احراز هویت (کلید رد شده)

اگه کلیدت اشتباه، ابطال‌شده، یا رونویسی‌شده باشه (مثلاً یه فاصله یا خط جدید اضافه موقع کپی)، سرور درخواست رو با وضعیت HTTP 401 (Unauthorized) رد می‌کنه.

راه‌حل:

  1. کلید رو دوباره از صفحه‌ی «کلیدهای API» کپی کن — فقط همون رشته، بدون فاصله‌ی اضافه‌ی اول یا آخرش.
  2. اگه کلید رو قبلاً ابطال کرده باشی، دیگه هیچ‌وقت کار نمی‌کنه — باید یکی جدید بسازی. جزئیاتش تو «امنیت کلید API».
  3. اگه مطمئنی کلید درسته ولی بازم 401 می‌گیری، احتمالاً ابزارت داره کلید رو یه‌جای دیگه (نه هدر Authorization) می‌فرسته — تنظیماتش رو با نمونه‌ی curl تو api-quickstart مقایسه کن.

مدلی که خواستی تو منو نیست

اگه یه شناسه‌ی مدل بدی که تو لیست مجاز کلیدت نیست — یا اصلاً فعال نیست، یا اصلاً وجود نداره — همون یه پیام رو می‌بینی، چون کلیدهای بنفش همیشه یه لیست مشخص از مدل‌ها دارن و همون لیست اول چک می‌شه:

Your plan does not include this model.

(کد model_not_permitted، وضعیت HTTP 403 — همین پیام برای کلید پرداخت به‌اندازه‌ی مصرف با لیست محدود هم میاد، نه فقط کلید طرح؛ کلمه‌ی «plan» تو پیام گمراه‌کننده‌ست.) یعنی این کلید اجازه‌ی استفاده از اون مدل رو نداره؛ باید یه شناسه از لیست خودش برداری. لیست مدل‌های فعال زنده‌ست و عوض می‌شه — یه شناسه که دیروز کار می‌کرد ممکنه امروز فعال نباشه.

راه‌حل: یه شناسه‌ی واقعی از لیست زنده‌ی مدل‌های فعال بردار — این مسیر مستقیم به gateway می‌زنه، پس مدل «auto»ی چت مرورگر اینجا شناخته‌شده نیست و همین خطا رو می‌ده، نه یه راه‌حل:

  • BGE-M3
  • Claude Haiku 4.5 — حدود ۱٬۲۴۹ تومان برای هر پیام معمولی
  • Claude Opus 5 — حدود ۶٬۲۴۵ تومان برای هر پیام معمولی
  • Claude Opus 5.5 — حدود ۴٬۹۹۶ تومان برای هر پیام معمولی
  • Claude Sonnet 4.6 — حدود ۳٬۷۴۷ تومان برای هر پیام معمولی
  • Claude Sonnet 5 — حدود ۲٬۴۹۸ تومان برای هر پیام معمولی
  • Claude Sonnet 5.5 — حدود ۲٬۴۹۸ تومان برای هر پیام معمولی
  • DeepSeek V4 Flash — حدود ۷۱ تومان برای هر پیام معمولی
  • Embed Multilingual V3
  • Gemini 3.1 Flash Lite — حدود ۳۵۴ تومان برای هر پیام معمولی
  • Gemini 3.1 Pro — حدود ۲٬۸۱۰ تومان برای هر پیام معمولی
  • Gemini 3.5 Flash — حدود ۲٬۱۰۸ تومان برای هر پیام معمولی
  • Gemma 4 26B A4B — حدود ۸۷ تومان برای هر پیام معمولی
  • Gemma 4 31B — حدود ۱۵۶ تومان برای هر پیام معمولی
  • GLM-4.7 Flash — حدود ۱۱۴ تومان برای هر پیام معمولی
  • GLM-5 — حدود ۱٬۱۶۱ تومان برای هر پیام معمولی
  • GPT Oss 120B — حدود ۴۴ تومان برای هر پیام معمولی
  • GPT-6 Astra — حدود ۱۲٬۴۹۰ تومان برای هر پیام معمولی
  • GPT-6 Luna — حدود ۱۲۵ تومان برای هر پیام معمولی
  • GPT-6.1 Sol — حدود ۲٬۴۹۸ تومان برای هر پیام معمولی
  • Grok 4.7 — حدود ۱٬۸۷۴ تومان برای هر پیام معمولی
  • Kimi K2 Thinking — حدود ۷۹۱ تومان برای هر پیام معمولی
  • Kimi K2.6 — حدود ۹۰۰ تومان برای هر پیام معمولی
  • Llama 3.3 70B Turbo — حدود ۹۷ تومان برای هر پیام معمولی
  • Llama 4 Scout 17B 16E — حدود ۹۴ تومان برای هر پیام معمولی
  • Mistral Large 3 — حدود ۵۵۲ تومان برای هر پیام معمولی
  • Mistral Small 3.2 24B Instruct — حدود ۷۰ تومان برای هر پیام معمولی
  • Multilingual E5 Large
  • Qwen3 235B A22B Instruct — حدود ۱۲۹ تومان برای هر پیام معمولی
  • Qwen3 Coder 480B A35B Turbo — حدود ۲۹۷ تومان برای هر پیام معمولی
  • Qwen3 Embedding 8B
  • Qwen3 VL 30B A3B — حدود ۱۶۶ تومان برای هر پیام معمولی
  • Qwen3.5 397B A17B — حدود ۶۸۱ تومان برای هر پیام معمولی
  • Qwen3.6 35B A3B — حدود ۱۹۶ تومان برای هر پیام معمولی
  • Qwen3.8 Max — حدود ۱٬۵۵۰ تومان برای هر پیام معمولی
  • Titan Embed Text V2

کیف پول خالیه

مسیر API هم به موجودی کیف پولت گیت شده. وقتی موجودی ته بکشه، همون کلید هر درخواستی که بفرستی با وضعیت HTTP 402 رد می‌شه — تا وقتی شارژ کنی.

راه‌حل: فقط کیف پولت رو تو «صورت‌حساب» شارژ کن. کلید عوض نمی‌شه، کلید جدیدی هم صادر نمی‌شه — همین کلیدی که همین الان داری، بلافاصله بعد از شارژ دوباره کار می‌کنه. چیزی رو کپی یا جایگزین نکن.

سقف طرحت پر شده

این فقط برای کلید اشتراک کدنویسی (plan) پیش میاد، نه کلید پرداخت به‌اندازه‌ی مصرف. اگه تو یه ابزار IDE یا خط‌فرمان، داخل پنل خطای خودِ ابزار، این پیام رو دیدی:

Your plan's usage limit is reached until HH:MM UTC. Use your pay-as-you-go key to continue.

(به‌جای HH:MM ساعت واقعی بازشدن سهمت رو می‌بینی، به وقت UTC — برای تهران خودت تبدیلش کن.) کد این خطا ALLOWANCE_EXHAUSTEDه، با وضعیت HTTP 403 — یعنی سهم ۵ساعته یا هفتگی طرحت پر شده؛ نه کلیدت اشتباهه، نه کیف پولت خالیه.

راه‌حل: دوباره اجرا کردن تا همون ساعت کمکی نمی‌کنه. دو راه داری: صبر کنی تا همون ساعت برسه، یا تو همون ابزار، کلیدت رو با یه کلید پرداخت به‌اندازه‌ی مصرف از «کلیدهای API» عوض کنی.

سقف این اجرا پر شده

اگه موقع ساختن کلید یه «سقف هر اجرا» (run cap) براش تعیین کرده باشی، همین که یه اجرا (یه سشن agent) به اون سقف برسه، همون کلید متوقف می‌شه — نه جایگزین. کلید جدیدی صادر نمی‌شه و چیزی برای کپی‌کردن تو IDE یا کدت نیست؛ فقط همون کلید رو می‌بنده، نه کل حسابت رو. علامتش: همون کلید HTTP 401 «Key is blocked» می‌گیری، بدون این‌که کیف پولت خالی شده باشه.

راه‌حل: برو «کلیدهای API» و روی «ادامه» بزن — همون کلید دوباره کار می‌کنه و لازم نیست چیزی رو دوباره تو IDE بذاری. اگه سقف براش کوتاهه، «تغییر سقف» رو بزن (سقف هر اجرا رو عوض می‌کنه و بعد خودش ادامه می‌ده). اعمال‌شدنش ممکنه تا حدود یک دقیقه طول بکشه، پس اگه بعد از «ادامه» بازم چندتا 401 گرفتی، یه‌کم صبر کن و دوباره امتحان کن.

بودجه‌ی کلید تموم شده

این با سقف هر اجرا فرق داره. اگه برای کلیدت یه «سقف این کلید» (بودجه‌ی کلی، نه سقف هر اجرا) تعیین کرده باشی و بعد از یه تجدید، نسخه‌ی جدیدش با بودجه‌ی باقی‌مونده‌ی صفر یا کمتر صادر بشه، همون کلید جدید متوقف صادر می‌شه. اینجا «ادامه» کار نمی‌کنه — جوابش می‌گه بودجه تموم شده، نه این‌که دوباره فعالش کنه.

راه‌حل: تو «کلیدهای API»، تنظیمات کلید رو باز کن و «سقف این کلید» رو بیشتر از چیزی که تا الان خرجش شده تعیین کن. همین که بودجه زیاد شد، کلید خودش دوباره فعال می‌شه — چیزی رو کپی یا جایگزین نکن.

چک‌لیست سریع

قبل از این‌که دنبال کمک بگردی:

  1. آدرس و کلید رو تازه از صفحه‌ی «کلیدهای API» کپی کن (نه از یه نسخه‌ی قدیمی).
  2. همون درخواست رو با curl (نمونه‌ی api-quickstart) امتحان کن — اگه اونم خطا داد، مشکل مطمئناً از تنظیمات سمت بنفشه، نه ابزارت.
  3. مطمئن شو شناسه‌ی مدلی که فرستادی هنوز تو <ModelList /> هست — نه «auto» (که فقط تو چت مرورگر کار می‌کنه، نه رو این مسیر).
  4. یه 401 غیرمنتظره؟ اول تو «کلیدهای API» چک کن کلیدت متوقف نشده باشه (سقف اجرا یا بودجه تموم‌شده) — اگه هست، «ادامه» بزن یا سقف/بودجه رو زیاد کن.

سوال‌های پرتکرار

چرا با curl جواب می‌گیرم ولی تو IDE‌ام نه؟
معمولاً یعنی IDE هنوز آدرس یا کلید قدیمی رو کش کرده. بعد از هر تجدید کلید یا تغییر تنظیمات، ابزار رو کامل ری‌استارت کن.
چطور مطمئن شم مشکل از بنفشه نه از خود ابزارم؟
همون درخواست رو با curl (از api-quickstart) بزن. اگه curl هم همون خطا رو داد، مشکل از تنظیمات سمت بنفشه؛ اگه curl جواب داد، مشکل تو تنظیمات ابزارته.