# Errors

> Tokens API যত error code ফেরত দেয়, প্রতিটার মানে আর করণীয়, error JSON-এর গড়ন, support ticket-এর জন্য request id, আর কোন error retry করবেন।

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-এর মতো:

```json
{
  "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"
  }
}
```

| Field        | নোট                                                                                                                                                                               |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code`       | স্থির, machine যা পড়তে পারে। এটাই ব্যবহার করুন।                                                                                                                                  |
| `type`       | বড় শ্রেণি: `authentication_error`, `permission_denied_error`, `insufficient_quota`, `rate_limit_error`, `invalid_request_error`, `api_error`, `server_error` বা `tokens_error`। |
| `message`    | মানুষের পড়ার জন্য। billing-এর error-এ [billing](/dashboard/billing)-এর link থাকে।                                                                                                |
| `request_id` | `x-tokens-request-id` header-এর মানই। প্রতিটা response-এর `x-tokens-request-id` header-এও এটা থাকে।                                                                                  |

`/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-এর তালিকা

| Status  | Code                                                                     | অর্থ                                                                                                                    | কী করবেন                                                                                    |
| ------- | ------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| 400     | `invalid_request`                                                        | `model` নেই (বা `Content-Type: application/json` নেই), `n` 1 থেকে 4-এর বাইরে, অথবা upstream request body ফিরিয়ে দিয়েছে | request ঠিক করুন। upstream ফিরিয়ে দিলে দেখুন আপনার পাঠানো parameter ওই model সাপোর্ট করে কি না |
| 400     | `model_not_available`                                                    | model catalog-এ আছে, কিন্তু এখন serve করা যাচ্ছে না                                                                      | `GET /v1/models` থেকে অন্য model বেছে নিন                                                   |
| 400     | `endpoint_not_supported_for_model`                                       | এই model যে provider-গুলো serve করে, তাদের কেউই এই endpoint-এর উত্তর দিতে পারে না (যেমন chat model-এ `/v1/responses`, `/v1/completions` বা embeddings) | `/v1/chat/completions` ব্যবহার করুন, নয়তো অন্য model বেছে নিন |
| 401     | `missing_api_key`                                                        | `Authorization: Bearer` বা `x-api-key` header নেই                                                                       | যে environment-এ tool চলছে, সেখানে `TOKENS_API_KEY` set করুন                                |
| 401     | `invalid_api_key`                                                        | key চেনা যাচ্ছে না                                                                                                      | key আবার copy করুন, নয়তো নতুন একটা বানান                                                    |
| 401/403 | `upstream_auth_error`                                                    | upstream provider gateway-র credential মানেনি। দোষটা আপনার key-এর নয়                                                   | পরে আবার চেষ্টা করুন বা model বদলান। request id সহ জানান                                    |
| 402     | `insufficient_credits`                                                   | plan-এর credit আর Wallet মিলিয়েও request-এর খরচ কুলায় না                                                              | [billing](/dashboard/billing)-এ টাকা যোগ বা renew করুন, অথবা `max_tokens` কমান               |
| 402     | `no_funding`                                                             | চালু কোনো plan নেই, Wallet-এও ব্যালান্স নেই                                                                              | plan নিন বা টাকা যোগ করুন                                                                   |
| 402     | `outstanding_debt`                                                       | আগের usage-এর কারণে ব্যালান্স মাইনাসে চলে গেছে                                                                          | টাকা যোগ করে সেটা মিটিয়ে দিন                                                               |
| 402     | `member_cap_reached`                                                     | Team অ্যাকাউন্ট (চালু থাকলে): আপনার member-এর মাসিক cap শেষ                                                              | আপনার team admin-কে বলুন                                                                    |
| 403     | `key_inactive`                                                           | key revoke বা rotate হয়ে গেছে                                                                                          | এখনকার secret ব্যবহার করুন                                                                  |
| 403     | `key_expired`                                                            | key-র মেয়াদ পেরিয়ে গেছে                                                                                               | নতুন key বানান                                                                              |
| 403     | `account_suspended`                                                      | অ্যাকাউন্ট suspend করা আছে                                                                                              | [Support](/docs/support)-এর সাথে যোগাযোগ করুন                                                |
| 403     | `model_not_allowed_on_key`                                               | এই key-র allowed তালিকায় model-টা নেই                                                                                  | তালিকার কোনো model ব্যবহার করুন, নয়তো অন্য key নিন                                          |
| 403     | `monthly_spend_cap_exceeded`                                             | key-র মাসিক spend cap শেষ (check-এ এই request-এর সবচেয়ে খারাপ ক্ষেত্রের খরচও ধরা হয়)                                    | `max_tokens` কমান, নতুন মাসের জন্য অপেক্ষা করুন, বা অন্য key নিন                              |
| 403     | `tier_permission_denied`                                                 | আপনার plan-এ এই model নেই, আর Wallet-এও ব্যালান্স নেই                                                                   | plan upgrade করুন, নয়তো pay-as-you-go-র জন্য Wallet-এ টাকা যোগ করুন                         |
| 404     | `model_not_found`                                                        | model id অচেনা বা বন্ধ (upstream model চিনতে না পারলেও এটাই আসে)                                                         | `GET /v1/models` থেকে হুবহু id-টা দেখে নিন                                                   |
| 404     | `unsupported_endpoint`                                                   | path বা method সাপোর্ট করা endpoint-এর কোনোটাই নয়                                                                       | endpoint-এর তালিকার জন্য [models and usage](/docs/models-and-usage) দেখুন                    |
| 404     | `anthropic_protocol_disabled`                                            | এই deployment-এ Messages API (`/v1/messages`) বন্ধ করা আছে | তার বদলে Chat Completions ব্যবহার করুন |
| 413     | `request_entity_too_large`                                               | body 10 MB-এর বেশি                                                                                                      | context বা attachment ছোট করুন                                                               |
| 429     | `rate_limited`                                                           | মিনিটে request-এর সীমা শেষ                                                                                              | `Retry-After` যত সেকেন্ড বলে, তত সেকেন্ড অপেক্ষা করুন                                         |
| 429     | `concurrency_limit`                                                      | আপনার অ্যাকাউন্টে একসাথে চলা request বেশি হয়ে গেছে                                                                      | `Retry-After` (2 সেকেন্ড) পর্যন্ত অপেক্ষা করুন, বা parallelism কমান                           |
| 429     | `window_exhausted`                                                       | plan-এর কোনো usage window (5-hour, weekly বা monthly) শেষ                                                               | reset পর্যন্ত অপেক্ষা করুন (`Retry-After`), নয়তো plan upgrade করুন                           |
| 429     | `model_limit_reached`                                                    | এই billing period-এ আপনার plan-এ এই model-এর বরাদ্দ শেষ, অন্য model-গুলো ঠিকই চলবে                                       | model বদলান, নয়তো reset পর্যন্ত অপেক্ষা করুন (`Retry-After`, message-এ তারিখ দেখানো হয়)       |
| 429     | `rate_limit_exceeded`                                                    | failover-এর সব উপায় শেষ হওয়ার পর upstream provider আমাদের rate limit করেছে                                              | backoff দিয়ে retry করুন। `Retry-After` থাকলে মানুন                                          |
| 500     | `lookup_failed`, `admission_error`, `catalog_error`, `usage_unavailable` | আমাদের দিকের ভেতরের error                                                                                                | backoff দিয়ে একবার-দুবার retry করুন, তাতে না হলে support-এ জানান                              |
| 502     | `upstream_unreachable`                                                   | এই model-এর কোনো upstream-এর সাথেই connect করা যায়নি                                                                    | backoff দিয়ে retry করুন, [status](/status) দেখুন                                            |
| 5xx     | `upstream_error`                                                         | upstream server error ফেরত দিয়েছে (status সরাসরি পাঠানো হয়েছে)                                                         | backoff দিয়ে retry করুন                                                                    |
| 503     | `no_upstream_available`                                                  | এই model-এর জন্য এখন কোনো upstream configure করা নেই                                                                     | অন্য model চেষ্টা করুন, [status](/status) দেখুন                                              |
| 503     | `model_not_priced`                                                       | model-এর দাম ঠিক করা নেই, তাই বিল করা যায় না                                                                           | অন্য model চেষ্টা করুন আর বিষয়টা জানান                                                      |
| 504     | `upstream_timeout`                                                       | upstream 600 সেকেন্ডের মধ্যে সাড়া দেয়নি, বা request পাঠানোর পর connection ভেঙে গেছে                                     | একবার retry করুন, আর request ছোট করা যায় কি না ভাবুন                                         |

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

## Request id আর support ticket

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

| Header                | Value                                                                                             |
| --------------------- | ------------------------------------------------------------------------------------------------- |
| `x-tokens-request-id` | এই request-এর জন্য gateway-র id। এটা সব সময় আমরাই বানাই।                                         |
| `x-request-id`        | আপনি নিজের `x-request-id` পাঠালে সেটাই, না পাঠালে `x-tokens-request-id`-এর মতোই                   |

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

```python
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](/dashboard/support)-এ ticket খোলার সময় এই জিনিসগুলো দিন: `x-tokens-request-id`, সময় (timezone সহ), endpoint, model আর status code। API key কখনো দেবেন না। আমরা request id ধরে usage-এর metadata রাখি, prompt-এর content রাখি না। তাই id থেকেই আপনার request খুঁজে বের করা যায়। আরও জানতে [support](/docs/support) দেখুন।

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

| Retry                                    | Codes                                                                  |
| ---------------------------------------- | ---------------------------------------------------------------------- |
| হ্যাঁ, `Retry-After`-এর পরে               | `rate_limited`, `concurrency_limit`, `rate_limit_exceeded`             |
| হ্যাঁ, exponential backoff দিয়ে          | `upstream_unreachable`, `upstream_error`, `upstream_timeout`, সব 500 error |
| শুধু reset-এর সময় পার হলে, loop-এ নয়    | `window_exhausted`, `model_limit_reached` (`Retry-After` কয়েক দিনও হতে পারে) |
| না, আগে কিছু ঠিক করুন                    | সব 400, 401, 402, 403, 404 ও 413 error                           |

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

---
Page: https://tokens.bd/bn/docs/errors