# त्रुटियाँ

हर एंडपॉइंट एक ही तरह विफल होता है: एक 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 | आवश्यक स्कोप वाली कुंजी का उपयोग करें। |
| `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`

किसी क्वेरी पैरामीटर का मान गलत है, जैसे `limit` का 1 से 100 के बाहर होना, `wait` का संख्या न होना, अज्ञात
`status` या `category`, या `storage` का `permanent` / `temporary` के अलावा कुछ होना (400)। `param` उसका नाम बताता है।

### `invalid_category`

`GET /openapi.json?category=` में ऐसी श्रेणी दी गई है जो मौजूद नहीं है (400)। `GET https://api.doitong.com/v1/categories` उन्हें सूचीबद्ध करता है।

### `invalid_cursor`

सूची कॉल का `cursor` इस सूची से संबंधित नहीं है (400)। बिना कर्सर के फिर से शुरू करें।

### `invalid_idempotency_key`

`Idempotency-Key` हेडर खाली है या 255 वर्णों से लंबा है (400)।

### `invalid_arguments`

MCP टूल कॉल में कोई आर्ग्युमेंट अनुपस्थित या गलत रूप में है (केवल MCP)। `param` आर्ग्युमेंट का नाम बताता है।

### `invalid_input`

मॉडल इनपुट सत्यापन में पास नहीं होता (422): अज्ञात पैरामीटर (संदेश निकटतम मान्य नाम सुझाता है),
आवश्यक पैरामीटर अनुपस्थित, गलत प्रकार, अनुमत सूची या सीमा से बाहर का मान, या अलग-अलग मानों के साथ कैनोनिकल और
नेटिव नाम दोनों दिए गए हैं। `param` पहली गलत पैरामीटर है और `details` उन सभी की सूची देता है।
कोई शुल्क नहीं लिया जाता।

### `unsupported_file`

किसी फ़ाइल का प्रकार स्वीकार्य नहीं है (422), जैसे असमर्थित एक्सटेंशन वाला अपलोड, या ऐसा `content_type`
जो एक्सटेंशन से मेल नहीं खाता।

### `invalid_webhook_url`

`webhook_url` सार्वजनिक `https://` URL नहीं है (422)। निजी, स्थानीय और सादे `http://` पते अस्वीकार किए जाते हैं।

### `missing_api_key`

एंडपॉइंट को API कुंजी चाहिए, लेकिन कोई भेजी नहीं गई (401)।

### `invalid_api_key`

कुंजी अज्ञात, रद्द या समाप्त हो चुकी है (401)।

### `insufficient_scope`

कुंजी में इस कॉल के लिए आवश्यक स्कोप नहीं है (403), जैसे रन के लिए `models:run`, या
अनुरोध और शेष राशि पढ़ने के लिए `models:read`। [प्रमाणीकरण](https://doitong.com/developers/docs/authentication#scopes) देखें।

### `account_disabled`

खाता बंद या निलंबित है (403)। इसकी कुंजियाँ अब काम नहीं करतीं।

### `not_found`

पथ मौजूद नहीं है (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`

मॉडल बैकएंड ने अनुरोध अस्वीकार किया या विफल हुआ (रन पर 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)।