لعملاء الذكاء الاصطناعي: تعليمات الإعداد خطوة بخطوة — /docs/agents.md، فهرس الوثائق — /llms.txt.
الأخطاء والحدود
حدود الطلبات والمهلات وأكواد أخطاء البوابة. لكل استجابة نوضح متى تحدث وما ينبغي فعله: إعادة إرسال الطلب أو تصحيحه.
الحدود#
الأرقام — من الحقل limits في استجابة GET /v1/capabilities: فهناك دائمًا القيم المحدّثة.
| الحد | القيمة | عند التجاوز |
|---|---|---|
| الطلبات في الدقيقة لكل مفتاح | 120، ونافذة 60 ثانية من أول طلب | 429 rate_limit_exceeded والترويسة Retry-After؛ ولا تستهلك رفضات البوابة 5xx من الحصة |
| الطلبات المتزامنة للحساب | محدودة | تنتظر الطلبات الزائدة في الطابور؛ وإن لم تنتظر — 429 queue_timeout |
| حجم جسم الطلب | 16 ميبيبايت | 413 |
| طول الاستجابة | حسب النموذج — الجدول أدناه | إن تجاوز سقف النموذج — يُقتطع إلى السقف دون خطأ |
| المفاتيح الفرعية | حتى 50 لكل مفتاح إدارة، ولكل مفتاح حتى 120 طلب في الدقيقة | لرفع السقوف — عبر الدعم |
طول الاستجابة حسب النموذج#
بدون max_tokens، تُدرج البوابة القيمة الافتراضية: في وضع عدم البثّ — أقصر، ليدخل الرد ضمن المهلات، وفي البثّ — سقف النموذج. وmax_completion_tokens — هو الحقل نفسه.
model | السقف | بدون بثّ | في البثّ |
|---|---|---|---|
MiniMaxAI/MiniMax-M2.7 | 8192 | 1500 | 8192 |
deepseek-ai/DeepSeek-V4-Flash-0731 | 32768 | 1500 | 32768 |
zai-org/GLM-5.3-Flash | 8192 | 3000 | 8192 |
المهلات#
| المرحلة | القيمة | ما يحدث |
|---|---|---|
| الانتظار للحصول على مكان في الطابور | 45 ث | 429 queue_timeout مع الترويسة Retry-After: 1 |
| بداية استجابة الشبكة، بثّ | 150 ث | 504 upstream_timeout؛ ويُخصم تقدير رموز الإدخال |
| بداية استجابة الشبكة، بدون بثّ | 150 ث | 504 upstream_timeout؛ ويُخصم تقدير رموز الإدخال |
| توليد الاستجابة | ≈ 300 ث | تقطع الشبكة التوليد: تأتي الاستجابة مع finish_reason: length — تابع بالطلب التالي |
| الفاصل بين chunkات البثّ | 30 ث | يُغلق التدفق: finish_reason: stop في الchunk joingonka-stream-stalled |
| إشارة النشاط في البثّ | 15 ث | تعليق : keep-alive — وتتجاهله عملاء SSE |
| فتح التدفق | 30 ث | قبل هذه اللحظة يأتي الرفض برمز استجابة، وبعدها — بالchunk joingonka-error |
| استجابة مبكرة بدون بثّ | 90 ث | تُعيد البوابة 200 وترسل مسافات كل 15 ث — ويبقى JSON صالحًا؛ ويأتي الخطأ بعد ذلك في الجسم بالحقل error، وتبقى الحالة 200 |
ما يُخصم عند المهلة
الطلب الذي تقبله الشبكة لا يمكن إلغاؤه. عند 504 upstream_timeout يُخصم تقدير رموز الإدخال، أما الإخراج فلا؛ وإعادة المحاولة خصم جديد. البث المقطوع قبل usage النهائي يُحتسب بالطريقة نفسها. اطلب الردود الطويلة مع stream: true.
رموز الأخطاء#
جسم الخطأ كائن error بحقول message, type, code, param؛ وليست كل الحقول موجودة في كل الأخطاء. اعتمد على الحالة وtype، وتحقق عبر code: نص message قد يتغير. تنسيق Anthropic في قسم تنسيق أخطاء Anthropic.
JSON
{
"error": {
"message": "Model is currently overloaded in the Gonka network",
"type": "rate_limit_exceeded",
"code": "upstream_rate_limited"
}
}| الاستجابة | متى | ما ينبغي فعله |
|---|---|---|
400 invalid_request_error | جسم غير صحيح: لا يوجد messages، أو الرسالة ليست كائنًا، أو الجسم ليس JSON؛ أو موديل غير معروف — مع param: model وقائمة الموديلات المتاحة في النص | صحّح الطلب وفق نص الخطأ |
400 invalid_request_error empty_content_after_normalization | الرسالة فارغة بعد التطبيع — مثل أن تحتوي على صورة فقط | أضف نصًا إلى الرسالة |
400 invalid_request_error web_search_privacy_sanitization_not_supported | إضافة web وprivacy-sanitization في الطلب نفسه | أبقِ واحدة منهما فقط |
400 invalid_request_error previous_response_id_not_supported conversation_not_supported item_reference_not_supported background_not_supported hosted_tool_choice_not_supported | OpenAI Responses: إشارة إلى رد محفوظ أو محادثة أو عنصر؛ الوضع الخلفي؛ اشتراط أداة مدمجة | أرسل السجل كاملًا في input |
400 api_error | رفضت الشبكة المعاملات — مثل قيمة reasoning_effort خارج قائمتها | صحّح القيمة وفق نص الخطأ |
401 authentication_error | المفتاح غير موجود أو مُبطَل أو بتنسيق غير معروف | تحقق من المفتاح في صفحة gate.joingonka.ai/keys |
402 insufficient_funds | الرصيد لا يكفي لتقدير الطلب؛ والمتبقي في balance_ngonka | اشحن الرصيد: gate.joingonka.ai/billing |
402 insufficient_funds | طلب بلا مفتاح لا يأتي من الموقع (is_demo: true) | مرّر مفتاح API |
402 child_key_limit_exceeded | تجاوز حد الإنفاق للمفتاح — يومي أو شهري أو إجمالي؛ والمتبقي في daily_remaining, monthly_remaining, total_remaining | ارفع حد المفتاح من صفحة gate.joingonka.ai/keys أو انتظر إعادة الضبط |
403 forbidden | مفتاح الإدارة gm- في طلب إلى الموديل؛ أو مفتاح API على مسار مخصص للوحة التحكم فقط | للطلبات استخدم مفتاح jg- أو gc-؛ وإدارة الحساب من لوحة التحكم |
404 invalid_request_error model_not_found | GET /v1/models/{model}: الموديل غير موجود في الكتالوج أو مخفي مؤقتًا | خذ المعرّف من GET /v1/models |
404 invalid_request_error not_found compact_not_supported | OpenAI Responses: /v1/responses/{id} وعناوين الحالة الأخرى، /v1/responses/compact | احتفظ بالسجل عندك؛ ولمستخدمي Codex CLI عيّن معرّف مزوّد خاصًا بك |
404 invalid_request_error | مسار غير معروف | تحقق من الطريقة والمسار والعنوان الأساسي |
413 invalid_request_error | جسم الطلب أكبر من الحد | اختصر الطلب |
415 invalid_request_error | الجسم ليس JSON وفق الترويسة: يلزم Content-Type: application/json | أرسل Content-Type: application/json |
429 rate_limit_exceeded | تجاوز عدد الطلبات في الدقيقة لكل مفتاح؛ وفي الجسم rate_limit مع limit, remaining, reset | انتظر عدد الثواني المذكور في Retry-After |
429 rate_limit_exceeded upstream_rate_limited | الموديل محمّل فوق طاقته في شبكة Gonka | أعد المحاولة بعد Retry-After أو اختر موديلًا آخر — النماذج |
429 rate_limit_exceeded queue_timeout queue_full | كل أماكن الشبكة مشغولة: الطابور ممتلئ أو انتهت مدة الانتظار | أعد المحاولة بعد Retry-After |
500 server_error | خطأ داخلي في البوابة | أعد المحاولة لاحقًا؛ وإذا تكرر، راسل الدعم وأرفق x-request-id |
501 not_implemented | POST /v1/embeddings: لا توجد موديلات تضمين في الشبكة | استخدم خدمة تضمين أخرى |
502 api_error upstream_unauthorized | رفض مزوّد الشبكة بيانات اعتماد البوابة — مفتاحك سليم | أعد المحاولة بعد دقيقة |
502 api_error | خطأ في شبكة Gonka؛ وcode من الشبكة إن أرسلته | أعد المحاولة بعد فاصل أو اختر موديلًا آخر |
503 model_unavailable model_outage model_initializing model_unstable model_not_served | الموديل غير متاح الآن وفق فحوص الشبكة: عطل أو قيد التشغيل أو عدم استقرار أو لا أحد يخدمه؛ والرفض فوري بلا انتظار | اختر موديلًا آخر — نص الخطأ سيرشدك إليه؛ والقائمة في النماذج |
503 service_unavailable | لا توجد عُقد متاحة | أعد المحاولة لاحقًا |
504 timeout upstream_timeout | قبلت الشبكة الطلب لكنها لم ترد في الوقت المحدد؛ وقد خُصم تقدير رموز الإدخال | للردود الطويلة استخدم stream: true؛ وإعادة المحاولة خصم جديد |
أخطاء داخل البث المفتوح#
قبل فتح البث يصل الرفض برمز استجابة عادي — كما لو لم يكن هناك بث. وبعد الفتح تصبح الحالة 200، ويصل الخطأ هكذا:
- Chat Completions — قطعة
joingonka-errorبحقلerror، ثم انقطاع بلا[DONE]. - بلا بث بعد رد مبكر — الحالة
200والجسم بحقلerror. - Anthropic Messages — حدث
event: error، ثم يُغلق البث. - OpenAI Responses — حدث
response.failed، والسبب فيresponse.error.code. - Legacy Completions —
data: {"error": …}، ثم[DONE].
SSE
data: {"id":"joingonka-error","object":"chat.completion.chunk","model":"MiniMaxAI/MiniMax-M2.7","choices":[],"error":{"message":"Gonka network error","type":"api_error"}}تنسيق أخطاء Anthropic#
POST /v1/messagesيرد بمغلّف Anthropic:{"type": "error", "error": {"type", "message"}}.- تحتفظ رفوض البوابة بـ
typeمن الجدول أعلاه (insufficient_fundsوmodel_unavailableوغيرها)؛ ولا يوجد حقلcodeفي هذا المغلّف — السبب في النص. - أخطاء صيغة الطلب —
invalid_request_error: لا رسائل أوmax_tokens، أو استدعاء أداة بلا اسم، أو موديل غير معروف. - مسار غير معروف —
not_found_error، وجسم كبير جدًا —request_too_large.
SSE
event: error
data: {"type":"error","error":{"type":"timeout","message":"Upstream timeout"}}ما الذي يُعاد#
- بعد فاصل من
Retry-After:429 - بفاصل متزايد — 1 ثم 2 ثم 4 ثوانٍ وهكذا:
500,502,503 service_unavailable,504 - بموديل آخر:
503 model_unavailable - لا تُعد المحاولة بلا تغيير — صحّح الطلب أو المفتاح أو الرصيد:
400,401,402,403,404,413,415,501
كل إعادة محاولة بعد 504 خصم جديد لتقدير الإدخال؛ وللردود الطويلة فعّل stream: true.
إذا تكرر الخطأ، راسل الدعم وأرفق x-request-id من ترويسات الاستجابة.