# خرابیاں

ہر اینڈ پوائنٹ ایک ہی طریقے سے ناکام ہوتا ہے: ایک HTTP اسٹیٹس اور ایک JSON لفافہ۔

```json
{
  "error": {
    "type": "invalid_request",
    "code": "invalid_input",
    "message": "duration must be one of 5, 10.",
    "param": "duration",
    "details": [ { "param": "duration", "message": "duration must be one of 5, 10." } ],
    "request_id": null,
    "doc_url": "https://doitong.com/developers/docs/errors#invalid_input"
  }
}
```

| فیلڈ | مطلب |
|---|---|
| `type` | خرابی کی وسیع قسم۔ اسی کی بنیاد پر طے کریں کہ کیا کرنا ہے۔ |
| `code` | درست وجہ، مستقل اور مشین کے ذریعے پڑھنے کے قابل۔ ہر کوڈ کا ایک سیکشن نیچے ہے؛ `doc_url` اس تک لے جاتا ہے۔ |
| `message` | انسان کے پڑھنے کے قابل وضاحت، جسے لاگ یا ڈیولپر کو دکھانا محفوظ ہے۔ |
| `param` | خرابی والا ان پٹ پیرامیٹر یا ہیڈر، اگر کوئی ہو۔ |
| `details` | ان پٹ کی خرابیوں کے لیے ملنے والا ہر مسئلہ: `[{ "param", "message" }]`۔ |
| `request_id` | متعلقہ درخواست، اگر موجود ہو۔ |

جو کال خرابی واپس کرتی ہے اس پر کچھ وصول نہیں کیا جاتا۔ جو درخواست قبول کیے جانے کے *بعد* ناکام ہو، اس کا اسٹیٹس
`failed` رہتا ہے، درخواست آبجیکٹ میں `error: { "type", "code", "message" }` شامل ہوتا ہے، اور رقم خودکار طور پر واپس کر دی جاتی ہے۔

## اقسام

| قسم | HTTP اسٹیٹس | کیا کریں |
|---|---|---|
| `invalid_request` | 400, 413 یا 422 | درخواست درست کریں۔ اسی کال کو دوبارہ بھیجنے پر پھر ناکامی ہوگی۔ |
| `authentication_error` | 401 | `Authorization: Bearer <key>` میں ایک درست کلید بھیجیں۔ |
| `permission_error` | 403 | مطلوبہ scope والی کلید استعمال کریں۔ |
| `not_found` | 404 | ماڈل id یا درخواست id چیک کریں۔ |
| `insufficient_credits` | 402 | API بیلنس کا ٹاپ اَپ کریں (خرابی میں `top_up_url`)۔ |
| `budget_exceeded` | 402 | کلید کا اپنا بجٹ ختم ہو چکا ہے۔ آخری حل: کلید کے مالک سے اسے بڑھانے کو کہیں۔ |
| `conflict` | 409 | وسیلہ ایسی حالت میں نہیں جس میں یہ کال کی جا سکے۔ |
| `rate_limited` | 429 | `Retry-After` سیکنڈ انتظار کریں، پھر دوبارہ کوشش کریں۔ |
| `upstream_error` | 502 | ماڈل کا بیک اینڈ ناکام ہو گیا۔ اسی `Idempotency-Key` کے ساتھ دوبارہ کوشش کرنا محفوظ ہے: یہ دوبارہ چلے گا؛ آپ سے رقم وصول نہیں کی گئی۔ |
| `service_unavailable` | 503 | API موقوف ہے یا کوئی انحصار دستیاب نہیں۔ بعد میں دوبارہ کوشش کریں۔ |
| `internal_error` | 500 | ہماری خرابی۔ دوبارہ کوشش کریں؛ برقرار رہے تو وقت اور `request_id` کے ساتھ سپورٹ سے رابطہ کریں۔ |

## کوڈز

### `invalid_request`

عمومی طور پر غلط تشکیل دی گئی درخواست (400)۔

### `invalid_json`

باڈی درست JSON نہیں ہے (400)۔

### `invalid_body`

باڈی درست JSON ہے لیکن آبجیکٹ نہیں؛ ماڈل ان پٹ ایک JSON آبجیکٹ ہونا چاہیے (400)۔

### `body_too_large`

باڈی 16 MB سے بڑی ہے (413)۔ بڑی فائلیں اپ لوڈ کریں اور اس کے بجائے ان کا URL بھیجیں (دیکھیں [فائلیں](https://doitong.com/developers/docs/files))۔

### `invalid_parameter`

کسی query پیرامیٹر کی قدر غلط ہے، مثلاً `limit` کی قدر 1 سے 100 کے باہر ہو، `wait` عدد نہ ہو، نامعلوم
`status` یا `category` ہو، یا `storage` کی قدر `permanent` / `temporary` کے علاوہ ہو (400)۔ `param` اس کا نام بتاتا ہے۔

### `invalid_category`

`GET /openapi.json?category=` ایسی category کا نام دیتا ہے جو موجود نہیں (400)۔ `GET https://api.doitong.com/v1/categories` ان کی فہرست دیتا ہے۔

### `invalid_cursor`

فہرست کی کال کا `cursor` اس فہرست سے متعلق نہیں (400)۔ cursor کے بغیر دوبارہ شروع کریں۔

### `invalid_idempotency_key`

`Idempotency-Key` ہیڈر خالی ہے یا 255 حروف سے زیادہ طویل ہے (400)۔

### `invalid_arguments`

MCP ٹول کال میں کوئی آرگیومنٹ موجود نہیں یا اس کی تشکیل غلط ہے (صرف MCP)۔ `param` آرگیومنٹ کا نام بتاتا ہے۔

### `invalid_input`

ماڈل ان پٹ توثیق میں کامیاب نہیں ہوتا (422): نامعلوم پیرامیٹر (پیغام قریب ترین درست نام تجویز کرتا ہے)،
مطلوبہ پیرامیٹر غائب، غلط قسم، مجاز فہرست یا حد سے باہر قدر، یا مختلف قدروں کے ساتھ canonical اور
native نام دونوں دیے گئے ہیں۔ `param` پہلی خلاف ورزی کرنے والے پیرامیٹر کا نام ہے اور `details` ان سب کی فہرست دیتا ہے۔
کچھ وصول نہیں کیا جاتا۔

### `unsupported_file`

فائل کی قسم قابل قبول نہیں (422)، مثلاً غیر معاون extension والی اپ لوڈ، یا ایسا `content_type`
جو extension سے مطابقت نہیں رکھتا۔

### `invalid_webhook_url`

`webhook_url` عوامی `https://` URL نہیں ہے (422)۔ نجی، مقامی اور سادہ `http://` پتے مسترد کیے جاتے ہیں۔

### `missing_api_key`

اینڈ پوائنٹ کو API کلید درکار ہے مگر کوئی کلید نہیں بھیجی گئی (401)۔

### `invalid_api_key`

کلید نامعلوم، منسوخ شدہ یا زائد المیعاد ہے (401)۔

### `insufficient_scope`

کلید میں اس کال کے لیے درکار scope موجود نہیں (403)، مثلاً run کے لیے `models:run`، یا
درخواستیں اور بیلنس پڑھنے کے لیے `models:read`۔ [تصدیق](https://doitong.com/developers/docs/authentication#scopes) دیکھیں۔

### `account_disabled`

اکاؤنٹ بند یا معطل ہے (403)۔ اس کی کلیدیں اب کام نہیں کرتیں۔

### `not_found`

یہ path موجود نہیں (404)۔

### `model_not_found`

اس id والا کوئی عوامی ماڈل موجود نہیں (404)۔ `GET https://api.doitong.com/v1/models` سے ماڈلز کی فہرست حاصل کریں۔

### `request_not_found`

آپ کے اکاؤنٹ میں اس id والی کوئی درخواست موجود نہیں (404)۔ دوسرے اکاؤنٹس کی درخواستیں کبھی دکھائی نہیں دیتیں۔

### `insufficient_credits`

اکاؤنٹ کا **API بیلنس** (API کریڈٹس، 1,000 API کریڈٹس = ⁨$1⁩ — Doitong ایپس کے کریڈٹس نہیں) اس کال کی قیمت پوری نہیں کرتا
(402)۔ کسی بھی رقم کی کٹوتی سے پہلے جواب بھیج دیا جاتا ہے۔ خرابی میں `top_up_url` شامل ہوتا ہے؛
[https://doitong.com/developers/dashboard#balance](https://doitong.com/developers/dashboard#balance) پر رقم شامل کریں اور دوبارہ کوشش کریں۔

```json
{ "error": { "type": "insufficient_credits", "code": "insufficient_credits",
             "message": "This request costs 560 API credits ($0.56); the API balance is 120 API credits ($0.12). Top up at https://doitong.com/developers/dashboard#balance",
             "top_up_url": "https://doitong.com/developers/dashboard#balance", "doc_url": "https://doitong.com/developers/docs/errors#insufficient_credits" } }
```

### `budget_exceeded`

یہ کال API کریڈٹس میں API کلید کے اپنے بجٹ سے تجاوز کر جائے گی (402)۔ بجٹ کلید کا مالک مقرر کرتا ہے؛ جب تک وہ اسے بڑھائے، دوبارہ کوشش کرنا مفید نہیں۔

### `conflict`

کال وسیلے کی موجودہ حالت سے متصادم ہے (409)۔

### `idempotency_mismatch`

`Idempotency-Key` پہلے ہی مختلف باڈی کے ساتھ استعمال ہو چکی ہے (409)۔ نئی کارروائی کے لیے نئی کلید استعمال کریں۔

### `idempotency_in_progress`

اسی `Idempotency-Key` والی درخواست ابھی بنائی جا رہی ہے (409)۔ اسے حاصل کرنے کے لیے کچھ دیر بعد دوبارہ کوشش کریں۔

### `request_active`

درخواست ابھی `queued` یا `running` ہے، اس لیے ابھی حذف کرنے کے لیے کوئی فائل نہیں (409)۔ مکمل ہونے کے بعد انہیں حذف کریں۔

### `not_cancelable`

درخواست پہلے ہی `succeeded` یا `failed` ہے اور اسے منسوخ نہیں کیا جا سکتا (409)۔

### `rate_limited`

موجودہ ونڈو میں کلید نے بہت زیادہ درخواستیں بھیجی ہیں (429)۔ `X-RateLimit-*` اور `Retry-After` ہیڈرز دیکھیں۔

### `too_many_inflight`

اکاؤنٹ میں پہلے ہی 10 درخواستیں `queued` یا `running` ہیں (429)۔ ان میں سے ایک مکمل ہو تو اگلی شروع کریں۔

### `upstream_error`

ماڈل کے بیک اینڈ نے درخواست مسترد یا ناکام کر دی (run پر 502، یا درخواست پر اس کوڈ کے ساتھ `failed`)۔ API کریڈٹس
واپس کر دیے جاتے ہیں۔ اگر بیک اینڈ نے خود ان پٹ مسترد کیا ہو تو کال اس کے پیغام کے ساتھ `422 invalid_input` واپس کرتی ہے۔

### `upstream_lost`

ماڈل کا بیک اینڈ اب درخواست کو نہیں پہچانتا، اس لیے کوئی نتیجہ کبھی نہیں آئے گا۔ یہ اس کوڈ کے ساتھ `failed`
(type `upstream_error`) پر ختم ہوتی ہے اور رقم واپس کر دی جاتی ہے۔ اسے دوبارہ چلائیں۔

### `timeout`

درخواست اپنی حد سے زیادہ دیر چلی (تصاویر کے لیے 15 منٹ، ویڈیو کے لیے 60، بصورت دیگر 30) اور روک دی گئی۔ یہ
اس کوڈ کے ساتھ `failed` پر ختم ہوتی ہے اور رقم واپس کر دی جاتی ہے۔

### `service_unavailable`

API عارضی طور پر موقوف ہے، یا فائل اپ لوڈز جیسا کوئی انحصار دستیاب نہیں (503)۔ بعد میں دوبارہ کوشش کریں۔

### `internal_error`

ہماری طرف کچھ خراب ہو گیا (500)۔ دوبارہ کوشش کریں؛ برقرار رہے تو سپورٹ سے رابطہ کریں۔

### `charge_failed`

اندرونی مسئلے کے باعث اکاؤنٹ سے رقم وصول نہیں کی جا سکی (500)۔ درخواست کو `failed` نشان زد کیا گیا ہے؛ کوئی رقم
نہیں کاٹی گئی۔ دوبارہ کوشش کریں۔

### `pricing_unavailable`

ماڈل کی قیمت تشکیل نہیں دی گئی، اس لیے فی الحال اس کی قیمت بتانا یا اسے چلانا ممکن نہیں (500)۔