أخطاء الاتصال الشائعة وكيفية إصلاحها

تكاد كل مشكلات الاتصال تعود إلى أربعة أشياء: العنوان، والمفتاح، ومعرّف النموذج، والرصيد. ابدأ بالفحص السريع أدناه، ثم ابحث عن رمز الحالة الخاص بك. أجسام الاستجابة المقتبسة هنا هي الاستجابات الفعلية لواجهة API (أكتوبر 2026).

فحص سريع#

# 1. The address is reachable — this request needs no key
curl https://api.cheaptokens.dev/v1/models

# 2. The key and the balance work — a tiny request (costs a fraction of a cent)
curl https://api.cheaptokens.dev/v1/chat/completions \
  -H "Authorization: Bearer $CHEAPTOKENS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek-ai/DeepSeek-V4-Flash-0731", "max_tokens": 5,
       "messages": [{"role": "user", "content": "ping"}]}'

إذا فشل الأمر الأول، فقد يكون السبب الشبكة من جانبك، أو خطأ مطبعي في العنوان — أو أن الخدمة نفسها غير متاحة مؤقتًا. إذا فشل الأمر الثاني فقط، فابحث عن رمز الحالة الخاص به أدناه. إذا نجح كلاهما لكن أداتك لا تعمل، فقارن إعدادات الأداة بهذين الأمرين.

401 — مفتاح API غير صالح#

{"error": {"message": "Invalid API key", "type": "authentication_error"}}

العملاء بأسلوب Anthropic يحصلون على الخطأ نفسه بصيغتهم:

{"type": "error", "error": {"type": "authentication_error", "message": "Invalid API key"}}

الأسباب:

• نُسخ المفتاح مع حرف ناقص أو مسافة أو علامات اقتباس؛
• تم تدوير المفتاح في لوحة التحكم — القديم لم يعد يعمل؛
• تم تعيين مفتاح من خدمة أخرى (مثل OpenAI) بدلًا من مفتاح CheapTokens؛
• متغير البيئة فارغ في هذا الطرفية: echo ${#CHEAPTOKENS_API_KEY} يطبع طوله.

تعرض لوحة التحكم المفتاح مرة واحدة فقط. إذا فُقد، اضغط Rotate للحصول على مفتاح جديد وحدّثه في كل مكان يُستخدم فيه.

402 — رصيد فارغ أو لا مفتاح في الطلب#

تعيد واجهة API رمز 402 في حالتين مختلفتين:

1. الرصيد مستنفد. تُدفع الطلبات من الرصيد؛ وعندما ينفد، يتوقف المفتاح مؤقتًا. اشحن الرصيد في لوحة التحكم وتمر الطلبات مرة أخرى.
2. الطلب لا يحتوي على مفتاح على الإطلاق. إذا كان ترويسة Authorization (أو x-api-key لعملاء أسلوب Anthropic) مفقودًا، تجيب واجهة API برمز 402 مع النوع insufficient_funds. تحقق من أن أداتك ترسل المفتاح فعلًا: أسلوب OpenAI هو Authorization: Bearer <key>.

404 — عنوان خاطئ#

{"error": {"message": "Invalid URL (GET /v1/chat/completion)", "type": "invalid_request_error", "param": null, "code": null}}

المسار فيه خطأ مطبعي — هنا completion بدلًا من completions. أسباب شائعة أخرى:

• عنوان URL الأساسي لا يحتوي على /v1. يحتاج عملاء أسلوب OpenAI إلى https://api.cheaptokens.dev/v1. بدون /v1 يخطئ الطلب واجهة API وتحصل على صفحة HTML 404 عادية بدلًا من JSON.
• /v1 مرتين. بعض العملاء يضيفون /v1 بأنفسهم؛ عندئذٍ يجب أن يكون عنوان URL الأساسي هو الجذر، https://api.cheaptokens.dev. عملاء أسلوب Anthropic يستخدمون دائمًا عنوان الجذر.

400 — النموذج غير موجود#

{"error": {"message": "Model \"deepseek-v4-flash\" not found. Available: …", "type": "invalid_request_error", "param": "model"}}

يجب أن يكون معرّف النموذج هو المعرّف الكامل، بما في ذلك البادئة قبل الشرطة المائلة: deepseek-ai/DeepSeek-V4-Flash-0731، وليس deepseek-v4-flash. لا يهم حالة الأحرف الكبيرة أو الصغيرة. تسرد رسالة الخطأ المعرّفات المتاحة، والقائمة الكاملة موجودة دائمًا على GET /v1/models.

يعود 400 أيضًا لجسم طلب مشوّه — على سبيل المثال مصفوفة messages فارغة (messages field is required and must be a non-empty array) أو رسالة بدون role.

413 — الطلب كبير جدًا#

جسم الطلب محدود بـ 16 ميغابايت. يمكن أن يصل إليه الوكلاء بوضع ملفات أو سجلات ضخمة في السياق. أرسل فقط الأجزاء التي يحتاجها النموذج وقلّص مخرجات الأدوات الطويلة.

429 — طلبات كثيرة جدًا#

إذا تلقيت 429، فتباطأ. تتضمن الاستجابة ترويسة Retry-After بعدد الثواني التي يجب الانتظارها. تعيد حزم OpenAI SDK الرسمية المحاولة تلقائيًا (max_retries)؛ في كودك الخاص، انتظر Retry-After قبل المحاولة التالية.

503 — النموذج غير متاح مؤقتًا#

قد يكون النموذج غير متاح مؤقتًا؛ عندئذٍ تجيب واجهة API برمز 503 مع النوع model_unavailable، وتعرض بطاقة النموذج على الموقع "غير متاح مؤقتًا". أعد المحاولة لاحقًا أو بدّل حقل model إلى نموذج آخر — يبقى المفتاح والعنوان كما هما.

فترات انتظار طويلة ومهلات#

نماذج الاستدلال مثل zai-org/GLM-5.3-Flash تفكر قبل الإجابة، لذا قد يستغرق الرمز الأول بعض الوقت. استخدم البث أو ارفع مهلة العميل — على سبيل المثال timeout=120 في OpenAI SDK.