Errors

Tokens gateway যত API error code ফেরত দেয়, এই পেজে সবগুলোর তালিকা আছে: কোনটার মানে কী, আর retry করা যাবে কি না। আপনার code-এ branch করবেন code field দেখে। message পড়ার জন্য মানুষের, ওটা বদলে যেতে পারে।

Error JSON-এর গড়ন#

OpenAI-style endpoint-গুলোতে (/v1/chat/completions, /v1/completions, /v1/responses, /v1/embeddings, /v1/models) gateway নিজে যে error তৈরি করে, সেগুলো দেখতে OpenAI-এর error-এর মতো:

{
  "error": {
    "message": "Prepaid wallet balance is insufficient for this request. Top up your wallet in the dashboard: https://tokens.bd/dashboard/billing",
    "type": "insufficient_quota",
    "code": "insufficient_credits",
    "param": null,
    "request_id": "8f0c7a4e-2b1d-4c55-9a51-3f7e2d9b6c10"
  }
}

/v1/messages আর /v1/messages/count_tokens-এ প্রতিটা error-ই Anthropic-এর গড়নে আসে, error-টা Tokens তুলুক বা upstream provider: {"type": "error", "error": {"type": "...", "message": "...", "code": "..."}, "request_id": "..."}। Anthropic-এর গড়নের সাথে Tokens code যোগ করে দেয়, তাই নিচের code ধরে আপনি আগের মতোই branch করতে পারবেন। provider-এর ভেতরের তথ্য ফাঁস না হওয়ার জন্য upstream error-এর message বদলে একটা সাধারণ message বসিয়ে দেওয়া হয়। তবে HTTP status আর code থেকে error-টা কোন ধরনের, তা বোঝা যায়।

Error code-এর তালিকা#

gateway আপনাকে কিছু ফেরত দেওয়ার আগেই 429, 502, 503, 504 আর connection error হলে অন্য upstream source-এ failover করে নেয়। তাই আপনি যদি upstream error দেখেন, তার মানে ওই model-এর সব configured source-ই fail করেছে, নয়তো শেষটা করেছে।

Request id আর support ticket#

প্রতিটা response-এ, সফল হোক বা error, দুটো header থাকে:

নিজের x-request-id পাঠালে আমাদের id আর আপনার log মেলাতে সুবিধা হয়। OpenAI Python SDK-তে header পড়তে চাইলে:

raw = client.chat.completions.with_raw_response.create(
    model="deepseek/deepseek-v4.1-flash",
    messages=[{"role": "user", "content": "ping"}],
)
print(raw.headers.get("x-tokens-request-id"))
completion = raw.parse()

curl-এ header দেখতে -i যোগ করুন। support-এ ticket খোলার সময় এই জিনিসগুলো দিন: x-tokens-request-id, সময় (timezone সহ), endpoint, model আর status code। API key কখনো দেবেন না। আমরা request id ধরে usage-এর metadata রাখি, prompt-এর content রাখি না। তাই id থেকেই আপনার request খুঁজে বের করা যায়। আরও জানতে support দেখুন।

Retry-র নির্দেশিকা#

কাজে দেয় এমন backoff: প্রায় 1 সেকেন্ড দিয়ে শুরু করুন, প্রতি চেষ্টায় দ্বিগুণ করুন, সাথে একটু random jitter যোগ করুন, 30 সেকেন্ডে সীমা টানুন, আর 4 বা 5 বার চেষ্টার পর থামুন। Retry-After থাকলে অন্তত ততক্ষণ অপেক্ষা করুন। retry মানেই নতুন request, সফল হলে তার বিল হয়। আবার OpenAI আর Anthropic SDK এই error-গুলোর কিছু নিজেরাই retry করে, তাই নিজের loop বসানোর আগে max_retries দেখে নিন। পুরো backoff উদাহরণ rate limits পেজে আছে, আর agent-এর নির্দিষ্ট সমস্যার সমাধান troubleshooting পেজে।