Troubleshooting (সমস্যা সমাধান)

নিচে নিজের সমস্যার লক্ষণটা খুঁজে নিন, তারপর সেই সমাধান করুন। Tokens API-র বেশিরভাগ error-এর response body-তে একটা নির্দিষ্ট error.code থাকে। HTTP status-এর চেয়ে এই code অনেক বেশি কথা বলে, তাই শুরুতে সেটাই পড়ুন:

curl -i https://tokens.bd/v1/models -H "Authorization: Bearer $TOKENS_API_KEY"

-i দিলে x-tokens-request-id-ও ছাপা হয়। এটা সরিয়ে রাখুন, কারণ support এটা চাইবে। একসাথে অনেক কিছু fail করলে নিজের setup ঘাঁটার আগে /status দেখে নিন।

401: missing_api_key বা invalid_api_key#

লক্ষণ: GET /v1/models সহ প্রতিটা request সাথে সাথে fail করছে।

সমাধান:

• missing_api_key: gateway-তে কোনো key-ই পৌঁছায়নি। key পাঠান Authorization: Bearer <key> বা x-api-key: <key> হিসেবে। shell-এ echo $TOKENS_API_KEY চালান (PowerShell-এ echo $env:TOKENS_API_KEY), আর দেখুন এই session-এ variable-টা ফাঁকা কিনা।
• invalid_api_key: key ভুল, revoke করা, অথবা rotate হয়েছে। key শুরু হয় tok_live_ দিয়ে, তার পরে 48টা hex character। paste করার সময় কিছু কাটা পড়েছে কিনা, বাড়তি quote আছে কিনা বা শেষে newline ঢুকেছে কিনা দেখুন। rotate করলে পুরোনো secret সাথে সাথে অচল হয়ে যায়, তাই প্রতিটা client-এ নতুন key বসান। key হারিয়ে ফেলেছেন? key একবারই দেখানো হয়, তাই /dashboard/keys-এ গিয়ে নতুন একটা বানিয়ে নিন।

403: model_not_allowed_on_key বা tier_permission_denied#

লক্ষণ: কিছু model চলছে, বাকিগুলোতে 403 আসছে।

সমাধান:

• model_not_allowed_on_key: key বানানোর সময় allowed-models list দেওয়া হয়েছিল, আর তাতে এই model নেই। allow-list তৈরির পরে বদলানো যায় না, তাই যে model লাগবে সেগুলো দিয়ে নতুন key বানান।
• tier_permission_denied: আপনার plan-এ এই model নেই, আবার এর দাম মেটানোর মতো Wallet ব্যালান্সও নেই। যে model আপনার plan-এ আছে সেটা নিন, Wallet-এ টাকা যোগ করুন, অথবা /dashboard/billing-এ plan বদলান। দেখুন Plans and wallet।
• monthly_spend_cap_exceeded: key তার monthly spend cap ছুঁয়ে ফেলেছে। পরের মাস পর্যন্ত অপেক্ষা করুন, নয়তো বেশি cap-এর key নিন।
• key_inactive, key_expired, account_suspended: key বা অ্যাকাউন্ট বন্ধ করে দেওয়া হয়েছে। support-এর সাথে যোগাযোগ করুন।

GET /v1/models ঠিক সেই model-গুলোর তালিকা দেয়, যা এই key এখন ব্যবহার করতে পারে। বেশিরভাগ 403-এর প্রশ্ন এতেই মিটে যায়।

402: insufficient_credits#

লক্ষণ: যে request আগে চলত, সেগুলো হঠাৎ 402 দিয়ে fail করছে। এর সাথে সম্পর্কিত code আছে no_funding (কোনো active plan নেই, আবার Wallet-এ টাকাও নেই), outstanding_debt (message-এ যে ব্যালান্স দেখানো আছে সেটা মিটিয়ে দিন) আর member_cap_reached।

সমাধান: আপনার plan-এর credit আর Wallet মিলিয়েও request-টার খরচ কুলাচ্ছে না। /dashboard/billing-এ গিয়ে টাকা যোগ করুন, নয়তো renew করুন। ডলারে কমপক্ষে $5, টাকায় কমপক্ষে ৳500 যোগ করা যায়। সাবস্ক্রিপশন প্রতি মেয়াদে একবারের পেমেন্ট, নিজে থেকে renew হয় না। তাই plan চুপচাপ শেষ হয়ে গেলে ঠিক এই লক্ষণই দেখা যায়।

ব্যালান্স কমে এলে উত্তর মাঝপথে থেমে যাওয়াটাও একই সমস্যা, শুধু একটু হালকা রূপে। ব্যালান্সে যতটা কুলায়, gateway max_tokens কমিয়ে ততটাতে নামিয়ে আনে (সর্বনিম্ন 16)। টাকা যোগ করুন, আর Notifications থেকে low-balance alert চালু করে রাখুন।

429: window_exhausted, rate_limited আর concurrency_limit#

তিন রকম 429, তিনটার সমাধান আলাদা। error.code আর Retry-After header পড়ুন। Tokens X-RateLimit-* header পাঠায় না।

সীমা অ্যাকাউন্টভিত্তিক, key-ভিত্তিক নয়। তাই বেশি key বানালে সীমা বাড়ে না। বিস্তারিত Rate limits পাতায়। rate_limit_exceeded code-সহ 429 আসে upstream provider থেকে। gateway আগেই অন্য source-এ যাওয়ার চেষ্টা করেছে। তাই একটু থেমে আবার চেষ্টা করুন, নয়তো অন্য model নিন।

404: model_not_found#

লক্ষণ: আপনি নিশ্চিত model-টা আছে, তবু model_not_found (বা 400 model_not_available) আসছে।

সমাধান: model ID হুবহু লিখতে হয়, provider prefix-সহ। যেমন deepseek/deepseek-v4.1-flash, শুধু deepseek-v4.1-flash নয়। আপনার key সত্যিই কোন কোন ID ব্যবহার করতে পারে, দেখে নিন:

curl -s https://tokens.bd/v1/models -H "Authorization: Bearer $TOKENS_API_KEY" | jq -r '.data[].id'

model_not_available মানে ID ঠিক আছে, কিন্তু model-টা এখন চালানো যাচ্ছে না। /models থেকে অন্য একটা বেছে নিন।

404 unsupported_endpoint আলাদা ব্যাপার। এর মানে, path-টা এমন যা Tokens চালায় না (images, audio, files, batches, assistants, fine-tuning আর moderations চলে না), অথবা base URL ভুল। পরের অংশটা দেখুন।

Agent বলছে "model not found" বা 404: ভুল base URL#

সেটআপের সবচেয়ে সাধারণ ভুল এটাই। tool দুই দলে পড়ে:

Claude Code-এ /v1 দিলে request যায় /v1/v1/messages-এ। আবার OpenAI-ধরনের tool-এ /v1 বাদ দিলে request যায় site root-এর /chat/completions-এ। দুটোরই ফল 404, আর অনেক agent সেটাকে "model not found" বলে দেখায়। আপনার agent-এর config file মিলিয়ে দেখুন (Claude Code), অথবা Tokens CLI-কে দিয়ে লিখিয়ে নিন।

502, 503, 504: upstream error#

Code: 502 upstream_unreachable, 503 no_upstream_available, 504 upstream_timeout। উত্তর দেওয়ার আগে gateway অন্য upstream source-এ চেষ্টা করে। server error, 429, timeout, connection error আর provider-এর দিকের key বা model সমস্যায় সে এটা করে। তারপরও 5xx এলে বুঝতে হবে, যতগুলো source চেষ্টা করা হয়েছে সবগুলোই fail করেছে। backoff দিয়ে আবার চেষ্টা করুন (দুই-তিনবার), অন্য model নিন, আর /status-এ দেখুন upstream provider-দের কোনো incident চলছে কিনা। শুধু একটা model-এ error থেকে গেলে x-tokens-request-id দিয়ে ticket খুলুন।

লম্বা request নিয়ে চিন্তা নেই। gateway response header-এর জন্য 600 সেকেন্ড পর্যন্ত অপেক্ষা করে। তার আগেই আপনার নিজের client timeout হয়ে গেলে ওর timeout বাড়ান, নয়তো streaming-এ যান।

Streaming আটকে থাকে, বা একসাথে এসে পড়ে#

লক্ষণ: streamed response অনেকক্ষণ কিছুই দেখায় না, তারপর একসাথে এক চাঁড়ে চলে আসে, নয়তো কখনো শেষই হয় না।

সমাধান: আপনার client আর Tokens-এর মাঝখানে কিছু একটা server-sent events জমিয়ে রাখছে (buffering)।

• আগে curl -N আর "stream": true দিয়ে test করুন (cURL)। সেখানে stream হলে সমস্যা আপনার নিজের stack-এ।
• নিজের nginx-এর পেছনে থাকলে ওই route-এ proxy_buffering off; দিন, অথবা app থেকে X-Accel-Buffering: no পাঠান।
• নিজের middleware-এ text/event-stream response gzip করবেন না।
• কর্পোরেট proxy আর কিছু antivirus-এর HTTPS scanner পুরো response জমিয়ে রাখে। অন্য network-এ চেষ্টা করে নিশ্চিত হন।
• নিজের route handler-এ chunk আসার সাথে সাথে এগিয়ে দিন, পুরো body জমিয়ে নিয়ে নয়। দেখুন Node.js আর Streaming।

Tool call fail করে, বা model সেগুলো এড়িয়ে যায়#

লক্ষণ: tools-এর কথা বলা একটা 400 error আসে, অথবা model সাদামাটা লেখায় উত্তর দেয় আর আপনার function কখনো call করে না।

সমাধান: সব model tool calling সাপোর্ট করে না। /models-এ model-এর পাতা দেখুন, আর tool সাপোর্ট আছে এমন একটাতে যান। তারপর আপনার schema মিলিয়ে নিন: parameters অবশ্যই valid JSON Schema object হতে হবে, আর প্রতিটা tool result মিলে যাওয়া tool_call_id-সহ ফেরত পাঠাতে হবে। কোনো agent কেন কথা বলতে পারে অথচ file edit করে না, এটাও তার একটা কারণ। দেখুন Tool calling।

Windows: environment variable পাওয়া যাচ্ছে না#

• $env:TOKENS_API_KEY = "tok_live_your_key" শুধু এখনকার PowerShell window-র জন্য set করে।
• setx TOKENS_API_KEY "tok_live_your_key" শুধু নতুন window-র জন্য সেভ করে। যে window-এ চালিয়েছেন, সেটা এটা দেখে না। তাই নতুন terminal খুলুন (আর VS Code বা আপনার agent restart করুন)।
• cmd.exe-তে set TOKENS_API_KEY=tok_live_your_key লিখতে হয় value-র চারপাশে quote ছাড়া। quote দিলে সেগুলোও key-র অংশ হয়ে যায়।
• Windows PowerShell 5.1-এ curl আসলে Invoke-WebRequest-এর alias। এই docs-এর উদাহরণ চালাতে curl.exe ব্যবহার করুন।

তবুও আটকে আছেন#

/dashboard/support থেকে ticket খুলুন। সাথে দিন x-tokens-request-id, সময়, model ID আর error.code। API key দেবেন না। কী পাঠাতে হবে, তা Support পাতায় আছে, আর সব code-এর পুরো তালিকা আছে Errors-এ।