> لعملاء الذكاء الاصطناعي: تعليمات الإعداد خطوة بخطوة — [`/docs/agents.md`](https://gate.joingonka.ai/docs/agents.md)، فهرس الوثائق — [`/llms.txt`](https://gate.joingonka.ai/llms.txt).

# الأخطاء والحدود

حدود الطلبات والمهلات وأكواد أخطاء البوابة. لكل استجابة نوضح متى تحدث وما ينبغي فعله: إعادة إرسال الطلب أو تصحيحه.

## الحدود

الأرقام — من الحقل `limits` في استجابة `GET /v1/capabilities`: فهناك دائمًا القيم المحدّثة.

| الحد | القيمة | عند التجاوز |
| --- | --- | --- |
| الطلبات في الدقيقة لكل مفتاح | 120، ونافذة 60 ثانية من أول طلب | `429 rate_limit_exceeded` والترويسة `Retry-After`؛ ولا تستهلك رفضات البوابة 5xx من الحصة |
| الطلبات المتزامنة للحساب | محدودة | تنتظر الطلبات الزائدة في الطابور؛ وإن لم تنتظر — `429 queue_timeout` |
| حجم جسم الطلب | 16 ميبيبايت | `413` |
| طول الاستجابة | [حسب النموذج — الجدول أدناه](https://gate.joingonka.ai/ar/docs/errors#max-tokens) | إن تجاوز سقف النموذج — يُقتطع إلى السقف دون خطأ |
| المفاتيح الفرعية | حتى 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](https://gate.joingonka.ai/ar/docs/errors#anthropic-errors).

```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](https://gate.joingonka.ai/keys) |
| 402 `insufficient_funds` | الرصيد لا يكفي لتقدير الطلب؛ والمتبقي في `balance_ngonka` | اشحن الرصيد: [gate.joingonka.ai/billing](https://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](https://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` أو اختر موديلًا آخر — [النماذج](https://gate.joingonka.ai/ar/docs/models) |
| 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` | الموديل غير متاح الآن وفق فحوص الشبكة: عطل أو قيد التشغيل أو عدم استقرار أو لا أحد يخدمه؛ والرفض فوري بلا انتظار | اختر موديلًا آخر — نص الخطأ سيرشدك إليه؛ والقائمة في [النماذج](https://gate.joingonka.ai/ar/docs/models) |
| 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]`.

```text
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`.

```text
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` من ترويسات الاستجابة.