# ত্রুটি

প্রতিটি এন্ডপয়েন্ট একইভাবে ব্যর্থ হয়: একটি 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 or 422 | রিকোয়েস্ট ঠিক করুন। একই কল আবার চেষ্টা করলেও পুনরায় ব্যর্থ হবে। |
| `authentication_error` | 401 | `Authorization: Bearer <key>`-এ একটি বৈধ কী পাঠান। |
| `permission_error` | 403 | প্রয়োজনীয় স্কোপসহ একটি কী ব্যবহার করুন। |
| `not_found` | 404 | মডেল আইডি বা রিকোয়েস্ট আইডি পরীক্ষা করুন। |
| `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`, অথবা `permanent` / `temporary` ছাড়া অন্য কোনো `storage` (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`

এই আইডিসহ কোনো সর্বজনীন মডেল নেই (404)। `GET https://api.doitong.com/v1/models` দিয়ে মডেলের তালিকা দেখুন।

### `request_not_found`

আপনার অ্যাকাউন্টে এই আইডিসহ কোনো রিকোয়েস্ট নেই (404)। অন্য অ্যাকাউন্টের রিকোয়েস্ট কখনো দৃশ্যমান হয় না।

### `insufficient_credits`

অ্যাকাউন্টের **API ব্যালান্স** (API ক্রেডিট, ১,০০০ API ক্রেডিট = ১$ — 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` হিসেবে শেষ হয়
(ধরন `upstream_error`) এবং অর্থ ফেরত দেওয়া হয়। আবার চালান।

### `timeout`

রিকোয়েস্টটি নির্ধারিত সীমার চেয়ে বেশি সময় চলেছে (ছবির জন্য 15 মিনিট, ভিডিওর জন্য 60, অন্য সবকিছুর জন্য 30) এবং থামিয়ে দেওয়া হয়েছে। এটি
এই কোডসহ `failed` হিসেবে শেষ হয় এবং অর্থ ফেরত দেওয়া হয়।

### `service_unavailable`

API সাময়িকভাবে বিরতিতে আছে, অথবা ফাইল আপলোডের মতো কোনো নির্ভরতা ডাউন (503)। পরে আবার চেষ্টা করুন।

### `internal_error`

আমাদের দিক থেকে কোনো সমস্যা হয়েছে (500)। আবার চেষ্টা করুন; সমস্যা চলতে থাকলে সাপোর্টে যোগাযোগ করুন।

### `charge_failed`

অভ্যন্তরীণ সমস্যার কারণে অ্যাকাউন্টে চার্জ করা যায়নি (500)। রিকোয়েস্টটি `failed` হিসেবে চিহ্নিত করা হয়েছে; কোনো অর্থ নেওয়া হয়নি।
আবার চেষ্টা করুন।

### `pricing_unavailable`

মডেলের মূল্য কনফিগার করা নেই, তাই এই মুহূর্তে এর মূল্য জানানো বা চালানো যায় না (500)।