সাধারণ সংযোগ ত্রুটি এবং সেগুলো কীভাবে ঠিক করবেন

প্রায় প্রতিটি সংযোগ সমস্যাই চারটি বিষয়ে নেমে আসে: ঠিকানা, কী, মডেল আইডি এবং ব্যালেন্স। নিচের দ্রুত চেক দিয়ে শুরু করুন, তারপর আপনার স্ট্যাটাস কোড খুঁজুন। এখানে উদ্ধৃত রেসপন্স বডিগুলো API-এর প্রকৃত রেসপন্স (অক্টোবর ২০২৬)।

দ্রুত যাচাই#

# 1. The address is reachable — this request needs no key
curl https://api.cheaptokens.dev/v1/models

# 2. The key and the balance work — a tiny request (costs a fraction of a cent)
curl https://api.cheaptokens.dev/v1/chat/completions \
  -H "Authorization: Bearer $CHEAPTOKENS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "deepseek-ai/DeepSeek-V4-Flash-0731", "max_tokens": 5,
       "messages": [{"role": "user", "content": "ping"}]}'

প্রথম কমান্ডটি ব্যর্থ হলে কারণ আপনার দিকের নেটওয়ার্ক, ঠিকানায় টাইপো — অথবা পরিষেবাটি নিজেই সাময়িকভাবে অনুপলব্ধ হতে পারে। যদি শুধু দ্বিতীয়টি ব্যর্থ হয়, নিচে তার স্ট্যাটাস কোড দেখুন। যদি দুটোই কাজ করে কিন্তু আপনার টুলটি না করে, তাহলে টুলের সেটিংস এই দুটি কমান্ডের সাথে মিলিয়ে দেখুন।

401 — অবৈধ API কী#

{"error": {"message": "Invalid API key", "type": "authentication_error"}}

Anthropic স্টাইলের ক্লায়েন্টরা তাদের ফরম্যাটে একই ত্রুটি পায়:

{"type": "error", "error": {"type": "authentication_error", "message": "Invalid API key"}}

কারণসমূহ:

• কী কপি করার সময় একটি অক্ষর বাদ পড়েছে, একটি স্পেস বা কোটেশন আছে;
• ড্যাশবোর্ডে কী রোটেট করা হয়েছে — পুরোনোটি আর কাজ করে না;
• CheapTokens কী-এর বদলে অন্য সার্ভিসের (যেমন OpenAI) কী সেট করা আছে;
• এই টার্মিনালে এনভায়রনমেন্ট ভেরিয়েবলটি খালি: echo ${#CHEAPTOKENS_API_KEY} এর দৈর্ঘ্য প্রিন্ট করে।

ড্যাশবোর্ড একটি কী শুধু একবারই দেখায়। এটি হারিয়ে গেলে, নতুন একটি পেতে Rotate চাপুন এবং যেখানেই এটি ব্যবহৃত হয় সেখানে আপডেট করুন।

402 — খালি ব্যালেন্স বা অনুরোধে কোনো কী নেই#

API দুটি ভিন্ন পরিস্থিতিতে 402 ফেরত দেয়:

1. ব্যালেন্স শেষ হয়ে গেছে। অনুরোধগুলি ব্যালেন্স থেকে পরিশোধিত হয়; এটি শেষ হলে কী-টি পজ করা হয়। ড্যাশবোর্ডে টপ আপ করুন এবং অনুরোধগুলি আবার চলে যাবে।
2. অনুরোধে কোনো কী নেই। যদি Authorization হেডার (অথবা Anthropic-স্টাইলের ক্লায়েন্টের জন্য x-api-key) অনুপস্থিত থাকে, API টাইপ insufficient_funds সহ 402 উত্তর দেয়। পরীক্ষা করুন যে আপনার টুল সত্যিই কী পাঠায়: OpenAI স্টাইল হল Authorization: Bearer <key>।

404 — ভুল ঠিকানা#

{"error": {"message": "Invalid URL (GET /v1/chat/completion)", "type": "invalid_request_error", "param": null, "code": null}}

পাথটিতে একটি টাইপো আছে — এখানে completions এর পরিবর্তে completion। অন্যান্য সাধারণ কারণগুলো:

• বেস URL-এ /v1 নেই। OpenAI-স্টাইলের ক্লায়েন্টদের https://api.cheaptokens.dev/v1 প্রয়োজন। /v1 ছাড়া অনুরোধটি API-তে পৌঁছায় না এবং JSON-এর পরিবর্তে একটি সাধারণ HTML 404 পৃষ্ঠা পাওয়া যায়।
• /v1 দুইবার। কিছু ক্লায়েন্ট নিজেরাই /v1 যোগ করে; তখন বেস URL-টি রুট হতে হবে, https://api.cheaptokens.dev। Anthropic-স্টাইলের ক্লায়েন্টরা সর্বদা রুট ঠিকানা ব্যবহার করে।

400 — মডেল পাওয়া যায়নি#

{"error": {"message": "Model \"deepseek-v4-flash\" not found. Available: …", "type": "invalid_request_error", "param": "model"}}

The model ID must be the full ID, including the prefix before the slash: deepseek-ai/DeepSeek-V4-Flash-0731, not deepseek-v4-flash. Upper or lower case doesn't matter. The error message lists the available IDs, and the full list is always at GET /v1/models.

A 400 also comes back for a malformed request body — for example an empty messages array (messages field is required and must be a non-empty array) or a message without role.

413 — অনুরোধ খুব বড়#

অনুরোধের বডি 16 MB-তে সীমাবদ্ধ। এজেন্টরা কনটেক্সটে বিশাল ফাইল বা লগ ঢুকিয়ে এটি ছুঁয়ে ফেলতে পারে। মডেলের যেসব অংশ প্রয়োজন শুধু সেগুলোই পাঠান এবং দীর্ঘ টুল আউটপুট ছেঁটে দিন।

429 — অনেক বেশি অনুরোধ#

যদি আপনি 429 পান, গতি কমান। প্রতিক্রিয়াটিতে অপেক্ষা করার সেকেন্ড সংখ্যা সহ একটি Retry-After হেডার থাকে। অফিসিয়াল OpenAI SDK-গুলি স্বয়ংক্রিয়ভাবে পুনরায় চেষ্টা করে (max_retries); আপনার নিজের কোডে, পরবর্তী প্রচেষ্টার আগে Retry-After পর্যন্ত অপেক্ষা করুন।

503 — মডেল সাময়িকভাবে অনুপলব্ধ#

একটি মডেল সাময়িকভাবে অনুপলব্ধ থাকতে পারে; তখন API টি model_unavailable টাইপসহ 503 উত্তর দেয়, এবং সাইটে মডেল কার্ডে "temporarily unavailable" দেখায়। পরে আবার চেষ্টা করুন অথবা model ফিল্ডটি অন্য মডেলে পরিবর্তন করুন — কী এবং ঠিকানা একই থাকে।

দীর্ঘ অপেক্ষা এবং টাইমআউট#

zai-org/GLM-5.3-Flash-এর মতো রিজনিং মডেলগুলো উত্তর দেওয়ার আগে চিন্তা করে, তাই প্রথম টোকেন আসতে কিছুটা সময় লাগতে পারে। স্ট্রিমিং ব্যবহার করুন অথবা ক্লায়েন্ট টাইমআউট বাড়িয়ে দিন — উদাহরণস্বরূপ OpenAI SDK-তে timeout=120।