> AI ایجنٹس کے لیے: سیٹ اپ کی مرحلہ وار ہدایات — [`/docs/agents.md`](https://gate.joingonka.ai/docs/agents.md)، دستاویزات کا انڈیکس — [`/llms.txt`](https://gate.joingonka.ai/llms.txt)۔

# ایررز اور حدود

گیٹ وے کی درخواست کی حدیں، ٹائم آؤٹ اور ایرر کوڈز۔ ہر جواب کے بارے میں بتایا گیا ہے کہ یہ کب پیش آتا ہے اور کیا کرنا ہے: درخواست دہرائیں یا اسے درست کریں۔

## حدود

اعداد `GET /v1/capabilities` جواب کے `limits` فیلڈ سے ہیں: وہاں ہمیشہ تازہ ترین ویلیوز ہوتی ہیں۔

| حد | قدر | تجاوز پر |
| --- | --- | --- |
| فی کلید فی منٹ درخواستیں | 120، ونڈو 60 سیکنڈ پہلی درخواست سے | `429 rate_limit_exceeded` اور `Retry-After` ہیڈر؛ گیٹ وے کی 5xx مستردیاں کوٹہ خرچ نہیں کرتیں |
| اکاؤنٹ کی بیک وقت درخواستیں | محدود | زائد قطار میں انتظار کرتی ہیں؛ انتظار پورا نہ ہو تو — `429 queue_timeout` |
| درخواست باڈی کا سائز | 16 MiB | `413` |
| جواب کی لمبائی | [ماڈل کے لحاظ سے — نیچے دیا ٹیبل](https://gate.joingonka.ai/ur/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 سیکنڈ | `Retry-After: 1` ہیڈر کے ساتھ `429 queue_timeout` |
| نیٹ ورک جواب کا آغاز، اسٹریم | 150 سیکنڈ | `504 upstream_timeout`؛ ان پٹ ٹوکنز کا تخمینہ کاٹ لیا جاتا ہے |
| نیٹ ورک جواب کا آغاز، نان اسٹریم | 150 سیکنڈ | `504 upstream_timeout`؛ ان پٹ ٹوکنز کا تخمینہ کاٹ لیا جاتا ہے |
| جواب کی جنریشن | ≈ 300 سیکنڈ | نیٹ ورک جنریشن کاٹ دیتا ہے: جواب `finish_reason: length` کے ساتھ آتا ہے — اگلی درخواست سے جاری رکھیں |
| اسٹریم چنکس کے درمیان وقفہ | 30 سیکنڈ | اسٹریم بند ہو جاتی ہے: `joingonka-stream-stalled` چنک میں `finish_reason: stop` |
| اسٹریم میں ایکٹیویٹی سگنل | 15 سیکنڈ | کمنٹ `: keep-alive` — SSE کلائنٹس اسے نظر انداز کرتے ہیں |
| اسٹریم کھولنا | 30 سیکنڈ | اس لمحے تک انکار جواب کوڈ کی صورت میں آتا ہے، اس کے بعد — `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/ur/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` | کی کی خرچ کی حد 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` سے id لیں |
| 404 `invalid_request_error` `not_found` `compact_not_supported` | OpenAI Responses: `/v1/responses/{id}` اور دیگر اسٹیٹ ایڈریسز، `/v1/responses/compact` | تاریخ اپنے پاس رکھیں؛ Codex CLI کے لیے اپنا پرووائیڈر id سیٹ کریں |
| 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` | کی فی منٹ درخواستوں کی تعداد exceeded؛ باڈی میں — `limit, remaining, reset` کے ساتھ `rate_limit` | `Retry-After` میں جتنے سیکنڈ ہیں اتنا انتظار کریں |
| 429 `rate_limit_exceeded` `upstream_rate_limited` | Gonka نیٹ ورک پر ماڈل اوورلوڈڈ | `Retry-After` کے بعد دوبارہ کوشش کریں یا دوسرا ماڈل لیں — [ماڈلز](https://gate.joingonka.ai/ur/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/ur/docs/models) |
| 503 `service_unavailable` | کوئی نوڈ دستیاب نہیں | بعد میں دوبارہ کوشش کریں |
| 504 `timeout` `upstream_timeout` | نیٹ ورک نے درخواست قبول کی لیکن وقت پر جواب نہیں دیا؛ ان پٹ ٹوکنز کا تخمینہ کاٹ لیا گیا | طویل جوابات کے لیے — `stream: true`؛ دوبارہ کوشش نیا کٹوتی |

## کھلی اسٹریم میں ایررز

جب تک اسٹریم نہیں کھلی، انکار عام رسپانس کوڈ کے طور پر آتا ہے — جیسے اسٹریم کے بغیر۔ کھلنے کے بعد اسٹیٹس پہلے ہی `200` ہے، اور ایرر اس طرح آتا ہے:

- Chat Completions — `error` فیلڈ کے ساتھ `joingonka-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` منسلک کریں۔